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Dear Reader, 


Thank you for choosing AutoCAD Platform Customization: AutoLISP. This book is part of a family 
of premium-quality Sybex books, all of which are written by outstanding authors who combine 
practical experience with a gift for teaching. 


Sybex was founded in 1976. More than 30 years later, we're still committed to producing consis- 
tently exceptional books. With each of our titles, we’re working hard to set a new standard for 
the industry. From the paper we print on, to the authors we work with, our goal is to bring you 
the best books available. 


I hope you see all that reflected in these pages. I'd be very interested to hear your comments and 
get your feedback on how we're doing. Feel free to let me know what you think about this or any 
other Sybex book by sending me an email at contactus@sybex.com. If you think you've found 

a technical error in this book, please visit http: //sybex.custhelp.com. Customer feedback is 
critical to our efforts at Sybex. 


Best regards, 


A bude 


Chris Webb 
Associate Publisher 
Sybex, an Imprint of Wiley 


To my wife, who is also my best friend: It is hard 

to imagine that I would be writing this book if it 
were not for you. It was you, all those years ago, 
who encouraged me to step outside of my comfort 
zone and share what I knew with others. Thank you 
for the push I needed and for coming along on this 
journey with me. 
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Introduction 


Welcome to AutoCAD Platform Customization: AutoLISP! Have you ever thought to yourself, Why 
doesn’t the Autodesk® AutoCAD® program include every feature I need? Why isn’t it stream- 
lined for the type of work I perform? If so, you are not alone. AutoCAD at its core is a drafting 
platform that can be shaped and molded to more efficiently complete the tasks you perform on 

a daily basis and to enhance your company’s workflows with the use of programming. Take a 
deep breath. I did just mention programming, but programming isn’t something to fear. At first, 
just the idea of programming makes many people want to run in the opposite direction—myself 
included. The productivity gains are what propelled me forward. Programming isn’t all that dif- 
ferent from anything else you've tried doing for the first time. 

In many ways, learning to program is much like learning a foreign language. For many new 
to AutoLISP®, the starting place is often a basic understanding of syntax and the command func- 
tion. The command function allows you to leverage your knowledge of AutoCAD commands by 
being able to pass specific values to a command or pausing a command for a value. After you 
are comfortable with the syntax of AutoLISP and the command function, you can begin to learn 
additional functions that allow for the development of more robust and complex programs. 


About This Book 


AutoCAD Platform Customization: AutoLISP provides you with an understanding of the AutoLISP 
programming language and how it can help improve your productivity. This book is designed 
to be more than just an introduction to AutoLISP—a resource that can be used time and again 
when developing AutoLISP programs. As you page through this book, you will notice that it 
contains sample code and exercises that are based on real-world solutions. 

This book is the second in a series of three that focuses on customizing and programming 
AutoCAD. The three-book series as a whole is known as AutoCAD Platform Customization: User 
Interface, AutoLISP, VBA, and Beyond, which will be available as a printed book in late 2014/early 
2015. Book 1 in the series, AutoCAD Platform Customization: User Interface and Beyond, was pub- 
lished in early 2014 and focused on CAD standards and general customization of AutoCAD; 
book 3, AutoCAD Platform Customization: VBA, will be available in fall/winter 2014 and covers 
the VBA programming platform inside AutoCAD. 


XX | INTRODUCTION 


Is This Book for You? 


AutoCAD Platform Customization: AutoLISP covers many aspects of AutoLISP programming for 
AutoCAD on Windows and Mac OS. If any of the following are true, this book will be useful to 
you: 


@ You want to develop and load custom programs using the AutoLISP programming lan- 
guage for use in the AutoCAD drawing environment. 


You want to automate the creation and manipulation of drawing objects. 
You want to automate repetitive tasks. 


You want to help manage and enforce CAD standards for your company. 


AutoLISP in AutoCAD 


AutoLISP is the most popular and is the original supported programming language for the 
AutoCAD program. The reason for its popularity with new (and even veteran) programmers 
is that it is a natural extension of the AutoCAD program. There is no additional software to 
purchase, and AutoLISP can leverage the commands that Autodesk and third-party develop- 
ers expose at the Command prompt. For example, with a few simple lines of code you can set a 
layer as current and insert a title block with a specific insertion point, scale, and rotation. The 
block is then inserted on the layer you specified. To perform the same tasks manually, the end 
user would have to set a layer as current, choose the block they want to insert, and specify the 
properties of the block, which, in the case of a title block, are almost always the same. 

The AutoLISP programming language can be used to accomplish the following: 


@ Create custom functions that can be executed from the AutoCAD Command prompt 
@ Create and manipulate graphical objects in a drawing, such as lines, circles, and arcs 


@ Create and manipulate nongraphical objects in a drawing, such as layers, dimension styles, 
and named views 


Perform mathematical and geometric calculations 

Request input from or display messages to the user at the Command prompt 
Interact with files and directories in the operating system 

Read from and write to external files 


Connect to applications that support ActiveX and COM 


¢-¢ >è è è 


Display dialog boxes and get input from the end user 


AutoLISP code can be entered directly at the Command prompt or loaded using a LSP file. 
Once an AutoLISP program has been loaded, you can execute the custom functions from the 
Command prompt. Functions executed from the Command prompt can be similar to standard 
AutoCAD commands, but the programmer determines the prompts that should be displayed. 
It is also possible to use AutoLISP code with a command macro that is activated from the 
AutoCAD user interface or a tool on a tool palette. 
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What to Expect 


This book is organized to help you learn AutoLISP fundamentals and how to manage and 
implement custom AutoLISP programs. Additional resources and files containing the example 
code found throughout this book can be found on the companion web page, www. sybex.com/ 
go/autocadcustomization. 


Chapter 1: Quick Start for New AutoLISP Programmers In this chapter, you'll get an 
introduction to the AutoLISP programming language. I begin by showing you how to enter 
AutoLISP expressions at the Command prompt and execute standard AutoCAD commands. 
After that, you are eased into some basic programming concepts that allow you to perform 
conditional tests and repeat expressions. The chapter wraps up with creating and loading an 
AutoLISP file into the AutoCAD program. 


Chapter 2: Understanding AutoLISP In this chapter, you'll learn the fundamentals of 

the AutoLISP programming language. AutoLISP fundamentals include a look at the syn- 
tax and structure of an expression, how to use a function, and how to work with variables. 
Beyond just syntax and variables, you learn to use AutoCAD commands and group multiple 
AutoLISP expressions into custom functions. 


Chapter 3: Calculating and Working with Values In this chapter, you'll learn to work 
with mathematical and string-manipulation functions. Math functions allow you to per- 
form basic and advanced calculations based on object values or a value that the user might 
provide, whereas string-manipulation functions allow you to work with text-based values. 
Both numeric and textual values are used when creating or manipulating objects, adding 
annotations to a drawing, or displaying a message to the end user. Based on how the values 
are used, numeric values can be converted to strings and strings can be converted to numeric 
values. 


Chapter 4: Working with Lists In this chapter, you'll learn to work with the list data type. 
Lists are used throughout AutoLISP to provide 2D or 3D coordinate values and to define an 
object stored in a drawing. 


Chapter 5: Requesting Input and Using Conditional and Looping Expressions In this 
chapter, you'll learn to request input from the user, use conditional statements, and repeat 
expressions. Requesting input allows you to get values from the user and then use those 
values to determine the end result of the program. Conditional statements enable a program 
to make choices based on known conditions in a drawing or input from a user. After you 
understand conditional statements, you will learn to use them in conjunction with looping 
expressions to execute a set of expressions until a condition is met. 


Chapter 6: Creating and Modifying Graphical Objects In this chapter, you'll learn how to 
create, modify, and attach extended data to graphical objects using AutoCAD commands and 
AutoLISP functions. Graphical objects represent the drawing objects, such as a line, an arc, 

or a circle, that are displayed in model space or on a named layout. When modifying objects, 
you can choose to step through all the objects in a drawing or let the user select the objects to 
be modified. Extended data allows you to store information with an object that can be used to 
identify the objects your program creates or link objects to external database records. 


Chapter 7: Creating and Modifying Nongraphical Objects In this chapter, you'll learn 
how to create and modify nongraphical objects using AutoCAD commands and AutoLISP 


XXII 


INTRODUCTION 


functions. Nongraphical objects are used to control the appearance of graphical objects and 
store settings that affect the behavior of features in the AutoCAD program. Drawings sup- 
port two different types of nongraphical objects: symbol-table objects and dictionaries. 


Chapter 8: Working with the Operating System and External Files In this chapter, you 
will learn how to work with settings and files stored outside of the AutoCAD program. 
Settings can be stored in the Windows Registry and Plist files on Mac OS, and they can be 
used to affect the behavior of the AutoCAD program or persist values for your custom pro- 
grams between AutoCAD sessions. Files and folders stored in the operating system can be 
accessed and manipulated from the AutoCAD program, which allows you to set up project 
folders or populate project information in the title block of a drawing from an external file. 


Chapter 9: Catching and Handling Errors In this chapter, you will learn how to catch and 
handle errors that are caused by an AutoLISP function and keep an AutoLISP program from 
terminating early. AutoLISP provides functions that allow you to trace a function, see argu- 
ments as they are passed, catch an error and determine how it should be handled, and group 
functions together so all the actions performed can be rolled back as a single operation. 


Chapter 10: Authoring, Managing, and Loading AutoLISP Programs In this chapter, you 
will learn how to store AutoLISP code statements in a file, load and manage AutoLISP files, 
and deploy custom programs with plug-in bundles. Storing AutoLISP code in a file allows for 
its reuse in multiple drawings. When you load an AutoLISP file, all of the functions defined 
in the file are made available while the drawing remains open. Based on how you load or 
deploy an AutoLISP file, you might need to let the AutoCAD program know where your 
AutoLISP files are stored. 


Chapter 11: Using the Visual LISP Editor (Windows only) In this chapter, you will learn 
how to use the Visual LISP® Editor. The editor provides tools for writing, formatting, validat- 
ing, and debugging code in an AutoLISP file. Using the Visual LISP Editor, you can group 
AutoLISP files into project files, which make them easy to manage and compile. Compiling 
an AutoLISP file secures the source code contained in the file so that it can’t be altered by 
others. 


Chapter 12: Working with ActiveX/COM Libraries (Windows only) In this chapter, you 
will learn how to use ActiveX/COM libraries with AutoLISP. ActiveX provides access to 
additional functions, which allow for the creation and manipulation of drawing objects and 
AutoCAD application settings that aren’t easily accessible with standard AutoLISP func- 
tions. External applications, such as Microsoft Word and Excel, can also be accessed from the 
AutoCAD program when using ActiveX. 


Chapter 13: Implementing Dialog Boxes (Windows only) In this chapter, you will learn 
how to create and use dialog boxes with an AutoLISP program. Dialog boxes provide an 
alternative method of requesting input from the user and are implemented using Dialog 
Control Language (DCL). 


Companion Website 


An online counterpart to this book, the companion web page contains the sample files required 
to complete the exercises found in this book in addition to the sample code and project files used 
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to demonstrate some of the programming concepts explained in this book. In addition to the 
sample files and code, the web page contains resources that are not mentioned in this book. The 
companion web page can be found at www. sybex.com/go/autocadcustomization. 


Other Information 


This book assumes that you know the basics of your operating system—Windows or Mac OS 
X—and AutoCAD 2009 or later. When appropriate, I indicate when a feature does not apply to 
a specific operating system or release of AutoCAD. Most of the images in this book were taken 
using AutoCAD 2014 in Windows 8 and AutoCAD 2014 in Mac OS X 10.7. 

Since AutoCAD LT® doesn’t support AutoLISP, none of the content in this book applies to that 
software package. 


Styles and Conventions of This Book 


This book uses a number of styles and character formats—bold, italic, monotype face, all upper- 
case or lowercase letters, and others—to help you distinguish from the text you read, sample 
code you can try, text that you need to enter at the AutoCAD Command prompt, or the name of 
an object class or method in one of the programming languages. 

As you read through this book, keep the following conventions in mind: 


@ User-interface selections are represented by one of the following methods: 
@ Click the Application button > Options. 
@ On the ribbon, click the Manage tab > Customization > User Interface. 
@ Onthe menu bar, click Tools > Customize > Interface. 
@ Inthe drawing window, right-click and click Options. 
Keyboard input is shown in bold (for example, type cui and press Enter). 


Prompts that are displayed at the AutoCAD Command prompt are displayed as mono- 
space font (for example, Specify a start point:). 


@ AutoCAD command and AutoLISP function names are displayed in all lowercase letters 
with a monospace font (for example, Line or command). 


@ Example code and code statements that appear within a paragraph are displayed in mono- 
space font. Code samples might look like one of the following: 


@ (command ". circle" PAUSE 3) 
@ The alert method can be used to display an error message to the user. 


@ ; Draw a rectangle 
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Contacting the Author 


I hope that you enjoy AutoCAD Platform Customization: AutoLISP and that it changes the way 
you think about completing your day-to-day work. If you have any feedback or ideas that could 
improve this book, you can contact me using the following address: 


Lee Ambrosius: lee_ambrosius@hyperpics.com 


On my blog and website you'll find additional articles on customization and samples that I 
have written over the years. You'll find these resources here: 


Beyond the UI: http: //hyperpics.blogs.com 
HyperPics: www.hyperpics.com 


If you encounter any problems with this publication, please report them to the publisher. 
Visit the book’s website, www. sybex.com/go/autocadcustomization, and click the Errata link 
to open a form and submit the problem you found. 


Chapter 1 


Quick Start for New AutoLISP 
Programmers 


The AutoLISP® language and programming in general are two subjects that I have enjoyed for 
over 15 years now, but the same subjects make some people cringe and want to run in the oppo- 
site direction. Iam not going to claim AutoLISP is easy to learn, but it can be learned by anyone, 
whether or not they have a programming background. When I first set out to learn AutoLISP, I 
didn’t have any programming experience, but I wanted the benefits that AutoLISP could offer. 

I understand if you have some hesitation at the thought of learning AutoLISP, but you don’t 
need to feel that way—I will help you. This chapter will ease you into some core programming 
concepts and the AutoLISP programming language by exposing you to a variety of 
functions that are available. 

To complete the exercises in this chapter and be able to create and edit LSP files, you must 
have the following: 

For Windows users: Autodesk® AutoCAD® 2006 or later and the Notepad program 

For Mac OS users: Autodesk® AutoCAD® 2011 or later and the TextEdit program 


NOTE Although I mention AutoCAD 2006 or later, everything covered in this chapter should 
work without any problems going all the way back to AutoCAD® 2000 and even possibly 
earlier releases. 


Working with AutoLISP Expressions 


AutoLISP is a natural extension of AutoCAD, as it can be used seamlessly from the AutoCAD 
Command prompt. You can enter AutoLISP when no commands are active or when AutoCAD 
prompts you for a value. The programming statements used in AutoLISP are known as expres- 
sions. You can type expressions at the Command prompt as long as they start with an opening 
parenthesis [(] or an exclamation point (!). Follow those symbols with the functions you wish to 
execute and the arguments that provide data or further instruction. 

Each AutoLISP expression that starts with an opening parenthesis must also end with a clos- 
ing parenthesis. AutoLISP expressions must contain the same number of opening and closing 
parentheses—this is sometimes referred to as balancing parentheses. You can enter the opening 
and closing parentheses on separate lines, though. 
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Use these steps to gain a basic understanding of entering AutoLISP expressions at the 
AutoCAD Command prompt: 


1. 
2. 


Launch AutoCAD, if it is not already running. 
At the AutoCAD Command prompt, type ( and press Enter. 


AutoCAD responds with the prompt (_>, which is the program’s way of letting you know 
that AutoLISP has taken control. 


3. Press Esc to return to the standard AutoCAD Command prompt. 


10. 
11. 


12. 


At the AutoCAD Command prompt, type (+ 3 2) and press Enter. 


The AutoLISP expression is evaluated and returns a value of 5, which is the result of 
adding 3 and 2 together. The + (plus sign) is the function of the AutoLISP expression; 3 
and 2 are the arguments (in this case, data) that are passed to the function. The AutoLISP 
function you want to use must be the first item after the opening parenthesis. 


Type (* 3.5 2) and press Enter. 
The value 7.0 is returned as a result of multiplying 3.5 by 2. 
Type (setq rad (/ 0.375 2)) and press Enter. 


The value 0.1875 is returned as a result of dividing 0.375 by 2, but the same value is also 
assigned to the user-defined variable named rad with the setq function. AutoLISP expres- 
sions can be nested one inside of another, and they are evaluated from the 

innermost to the outermost expression. In this example, the expression (/ 0.375 2) is 
evaluated first and returns 0.1875. The next expression, (setq rad 0.1875), is evaluated 
and it also returns 0.1875. 


Type circle and press Enter. 
The AutoCAD circle command is started. 


At the Specify center point for circle or [3P/2P/Ttr (tan tan radius) ]: prompt, type 
(list © 5) and press Enter. 


The (list 0 5) expression returns a value of (0 5), which is a list of two values that 
presents the 2D coordinate of 0,5. The center of the circle is started at 0,5,0. 


At the Specify radius of circle or [Diameter]: prompt, type !rad and press Enter. 


AutoLISP evaluates the rad user-defined variable and returns its value to be used for the 
circle’s radius. The radius of the circle should be set to 0.1875. 


In the drawing area, select the new circle. 


On Windows, right-click in the drawing area and choose Properties. If you are using 
AutoCAD on Mac OS, secondary-click (two-finger tap or right-click) in the drawing area 
and choose Properties. 


In the Properties palette (Windows) or Properties Inspector (Mac OS)—see Figure 1.1— 
you should notice that the Center properties are set to 0,5,0 (X=0.0, Y=5.0, and Z=0.0) and 
the Radius property is set to 0.1875. 
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FIGURE 1.1 = 
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In this exercise, you did the following: 


@ Entered AutoLISP expressions at the AutoCAD Command prompt and stored values ina 
user-defined variable (see Chapter 2, “Understanding AutoLISP,” for more information) 


+ Used functions to perform basic math calculations (see Chapter 3, “Calculating and 
Working with Values,” for more information) 


@ Created a list that represented a 2D coordinate (see Chapter 4, “Working with Lists,” for 
more information) 


Working with Commands and Input 

In addition to calculating values with AutoLISP and passing those values to a command, you 
can execute a command as part of an AutoLISP expression using the command function. Input can 
also be requested and passed to a command or saved to a user-defined variable. 
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The following steps demonstrate how to create a layer named Circles with an AutoCAD 
Color Index (ACT) of 30 using the -layer command. You'll then draw a circle on the new layer 
with a user-specified center point and radius. 


1. At the AutoCAD Command prompt, type (command "-layer" "m" "Circles" "c" 
"3o" " " " ") and press Enter. 


The -layer command is started. The Make (m) option of the command is used to create 
the layer named Circles. After the Circles layer is created (or if it already exists), the Make 
option makes that layer current. The Color (c) option is then used to set the color of the 
Circles layer to ACI 30. 


2. Type (command "circle" PAUSE PAUSE) and press Enter. 


The circle command is started and the Specify center point for circle or [3P/2P/Ttr 
(tan tan radius)]: prompt is displayed. AutoCAD displays this prompt because the pre- 
defined PAUSE variable is used as the response to the command’s prompt for a value. 


3. At the Specify center point for circle or [3P/2P/Ttr (tan tan radius) ]: prompt, pick 
a point in the drawing area. 


4. Atthe Specify radius of circle or [Diameter]: prompt, type 0.1875 and press Enter. 
This command draws a circle with a radius of 0.1875 and places it on the Circles layer. 


5. At the Command prompt, type the following and press Enter: (setq cenPt (getpoint 
"\nSpecify a center point: ")). 


The getpoint function requests a point in the drawing area and can display an optional 
custom prompt to the user. 


6. At the Specify a center point: prompt, specify a point in the drawing area. 
The point you specified is assigned to the cenPt user-defined variable. 


7. At the Command prompt, type (setq rad (getreal "\nEnter radius: ")) and 
press Enter. 


The getreal function requests a numeric value. 
8. Atthe Enter radius: prompt, type 0.25 and press Enter. 
The value of 0.25 is assigned to the rad user-defined variable. 
9. Type (command "circle" cenPt rad) and press Enter. 


AutoCAD starts the circle command and draws a new circle based on the values 
assigned to the cenPt (center point) and rad (radius) user-defined variables. 


Now that you’ve entered some short expressions, let’s look at creating long expressions— 
expressions that can span multiple lines. Using the following steps, you will also see how to give 
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feedback to the user based on values they provided in the form of the center point and radius of 
the circle. 


1. 


Type (prompt (strcat "\nNew circle: "and press Enter. 


The prompt function allows you to return messages and values to the user, and the strcat 
function is used to combine multiple string values into a single string. This AutoLISP 
expression starts on this line and spans to the next line because no closing parentheses 
were provided. When an AutoLISP expression is not completed, the AutoCAD prompt 
displays the number of closing parentheses required to complete the current AutoLISP 
expression. For example, ((_> indicates you need to enter two closing parentheses to get 
back to the standard AutoCAD Command prompt. 


Type "\nCenter Point " (vl-princ-to-string cenpt) and press Enter. 


The vl-princ-to-string function allows you to display the current value assigned to a 
user-defined variable as a string. Here the v1-princ-to-string function converts the list 
that represents the center point of the circle to a string. 


Type "\nRadius: " (rtos rad) and press Enter. 

The rtos function converts a numeric value of the radius to a string. 

Type ) and press Enter. 

This closing parenthesis ends the strcat expression that we started in Step 1. 
Type ) and press Enter. 


This closing parenthesis ends the prompt expression that we started in Step 1. The 
message returned by the prompt function should look similar to the following: 


New circle: 
Center Point: (21.9627 6.18679 0.0) 
Radius: 0.2500nil 


In these exercises, you did the following: 


+ 


Used standard AutoCAD commands to create a layer and draw a circle (see Chapter 2 for 
more information) 


Requested input from the user and displayed information back to the user (see Chapter 5, 
“Requesting Input and Using Conditional and Looping Expressions,” for more information) 


Converted values from one type of data to another (see Chapters 3 and 4 for 
more information) 


Conditionalizing and Repeating Expressions 


Complex programs often contain branches (different sets of expressions that are used to handle 
different conditions or choices by the user), and they might loop (execute a set of expressions 
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multiple times). Conditional expressions allow your programs to use a programming concept 
known as branching. Branching gives your programs the ability to execute different expressions 
based on the input a user provides or the current value of a system variable. When modifying 
large sets of data or even prompting a user for input, you can use looping expressions to repeat 
a set of expressions while a condition is met. 

This exercise demonstrates some of the conditional and looping expressions that are 
available in AutoLISP: 


1. 


At the AutoCAD Command prompt, type (if (= (tblsearch "layer" "Circles") 
nil) and press Enter. 


The if function is used to test whether a condition is true or false. If the = comparison 
operator returns T, then the first expression is evaluated; otherwise, the second expres- 
sion is. The tblsearch function is used to check to see if a layer, linetype, or some other 
nongraphical object already exists in a drawing. 


Type (command "-layer" "m" "Circles" "c" "39" " " " ") and press Enter. 


This command creates the new Circles layer if it doesn’t exist in the drawing. 


3. Type (prompt "\nLayer already exists.") and press Enter. 


TIP 


Type )and press Enter. 


The closing parenthesis ends the if function. Either the Circles layer is created or the 
message Layer already exists. is displayed. Entering the four expressions again results 
in the displaying of the message. 


Type (setq cnt 0) and press Enter. 
The setq function defines a user-defined variable named cnt and assigns it the value of 0. 
Type (command "circle" (list © 0) 1) and press Enter. 


This command draws a circle at 0,0 with a radius of 1 on the “Circles” layer. 


If the new circle is not visible on the screen, pan and/or zoom to make it visible. 


Type (repeat 7 and press Enter. 


The repeat function is used to repeat a set of AutoLISP expressions a specific number of 
times. 


Type (setq cnt (1+ cnt)) and press Enter. 


The 1+ function increments the current value of cnt by 1 each time the expression is 
evaluated. 


Type (command "circle" (list © 0) (* (getvar "circlerad") 1.5)) and 
press Enter. 


Once you enter the expressions within the repeat loop and add the final closing paren- 
thesis to complete the expression, AutoCAD draws a new circle at 0,0 with a radius that 


10. 


11. 


FIGURE 1.2 


Drawing concen- 
tric circles with 


AutoLISP 
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is 1.5 times larger than the previous circle that was drawn. The previous radius used to 
create a circle with the circle command is stored in the circlerad system variable. The 
getvar function returns the current value of a system variable. 


Type (command "change" (entlast) " " "p" "c" cnt " ") and press Enter. 


The change command modifies the color of the recently drawn circle, or more specifically 
the last object in the drawing. The entlast function returns the last object added to the 
drawing. 


Type )and press Enter. 


The closing parenthesis ends the repeat function. Seven concentric circles, as shown in 
Figure 1.2, are drawn around the circle that was drawn outside of the repeat loop. Each 
circle drawn inside the repeat loop is assigned a different color, and the radius of each 
circle is 1.5 times larger than the next inner circle. 


In the previous exercise, you did the following: 


+ 


Used comparison operators and conditional functions to evaluate different expressions 
based on the results of a test condition (see Chapter 5 for more information) 


Used math-based functions to calculate the radius of a circle and to increment a counter 
used in a looping expression (see Chapter 3 for more information) 


Checked to see if a layer existed in the drawing (see Chapter 7, “Creating and Modifying 
Nongraphical Objects,” for more information) 


Repeated a set of AutoLISP expressions until a condition was met (see Chapter 5 for 
more information) 


Grouping Expressions 

Entering individual expressions can be helpful when you are first learning AutoLISP or when 
you are developing a new program, but it isn’t ideal for you to do each time you want to execute 
a set of AutoLISP expressions. The AutoLISP programming language allows you to define a 
custom function that can be executed at the Command prompt or from a command macro 
assigned to a user-interface element, such as a ribbon or toolbar button. 


7 
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The following steps demonstrate how to define a custom function named 
RectangularRevCloud that can be entered at the AutoCAD Command prompt: 


1. At the AutoCAD Command prompt, type the following and press Enter: 
(defun c:RectangularRevCloud ( / arclength) 


The defun function is used to define a function. The function defined is named 
RectangularRevCloud and contains one local variable named arclength. Local variables 
are accessible only to the function in which they are defined. 


2. Type the following and press Enter: 


(if (= (tblsearch "Layer" "RevCloud") nil) 
(command "-layer" "m" "RevCloud" "ec" "j" wee aN) 


The expressions test to see if a layer named RevCloud exists, and if it doesn’t, the layer is 
created and assigned the color red (1). 


3. Type the following and press Enter: 
(command "rectang" PAUSE PAUSE) 


The rectang command is used to draw a rectangle based on the two points the user 
provides. 


4. Type the following and press Enter: 


(if (> (setq arclength (abs (getvar "dimscale"))) 1) 
(setq arclength (* arclength 2)) 
(setq arclength 1.0) 

) 


The > operator and the if function determine whether the value of the dimscale system 
variable is greater than 1. If so, the value is used to set the arc length for the revision 
cloud that will be created from the rectangle. If the value of dimscale is less than 1, then 
the value of 1 is used. The calculated maximum arc length value is assigned to the user- 
defined variable named arclength. 


5. Type the following and press Enter: 


(command "revcloud" "a" (/ arclength 2) arclength "o" (entlast) "") 
(princ) 


) 


The revcloud command converts the rectangle that was drawn with the rectang com- 
mand to a revision cloud. The princ function keeps the last expression in the function 
definition from returning a value and allowing the function to “exit quietly.” The final 
closing parenthesis closes the defun function. 


6. Type the following and press Enter: 


(defun c:RRC ( / )(c:RectangularRevCloud) ) 
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The RRC custom function acts as an alias to the RectangulatRevCloud function and makes it 
easier to start the function from the Command prompt. 


7. Type RectangularRevCloud and press Enter. 


8. Atthe Specify first corner point or [Chamfer/Elevation/Fillet/Thickness/Width]: 
prompt, specify the first corner of the rectangle. 


9. At the Specify other corner point or [Area/Dimensions/Rotation]: prompt, specify the 
opposite corner of the rectangle. 


The rectangle is drawn on the layer “RevCloud” and converted to a revision cloud using 
the Object (0) option of the revcloud command; see Figure 1.3. 


FIGURE 1.3 
Converting a 
rectangle toa 
revision cloud 


10. Type RRC and press Enter. Specify the two corners of the rectangle. RRC is simply a short- 
cut to the new RectangularRevCloud function. 


In the previous exercise, you did the following: 


@ Grouped a set of AutoLISP expressions into a custom function to make it easier to execute 
the expressions (see Chapter 2 for more information) 


@ Accessed the value of a system variable (see Chapter 2 for more information) 


Storing and Loading AutoLISP Expressions 


AutoLISP expressions entered at the AutoCAD Command prompt are accessible from that 
drawing and only while that drawing remains open. You can store AutoLISP expressions in 
an LSP file that, once saved, can then be loaded into and executed from any drawing file that is 
opened in AutoCAD. The following exercise explains how to create and load an LSP file named 
acp_qs.lsp. 

If you are on Windows: 


1. Do one of the following: 
@ On Windows XP or Windows 7, click Start > [All] Programs > Accessories > Notepad. 


@ On Windows 8, on the Start Screen, type note and then select Notepad from the 
Search bar. 


2. In Notepad, click File > Save As. 


3. In the Save As dialog box, browse to the Documents (or My Documents) folder or the 
MyCustomF7 les folder that you created for the exercises and examples in this book. 
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In the File Name text box, type acp_qs. lsp. 
Click the Save As Type drop-down list and select All Files (**). 
Click the Encoding drop-down list and select ANSI. Click Save. 


2S ge 


In the text editor area, type the following expressions. Replace the square brackets and 
the text inside them with the current date and your name. 


; Created [Today's date] by [Your name] - Quick Start Examples 
; Zoom shortcuts 

(defun c:ZE ( / ) (command "._zoom" "e")) 

(defun c:ZW ( / ) (command "._zoom" "w"') ) 


; Repeat Purge command 3 times to remove nested objects 
; and remove zero lines and empty objects 
(defun c:P3 ( / ) 


(repeat 3 
(command ",_-purge" Wak" Wee tn) 
) 
(command "._-purge" "_z") 
(command "._-purge" "_e") 


; List which objects are in a selection set 
(defun c:ListObjects ( / selectedObjects count ent) 
(prompt "\nSelect objects to list: ") 
(setq selectedObjects (ssget) 
count 0 


(if (/= selectedObjects nil) 
(progn 
(while (> (sslength selectedObjects) count) 
(setq ent (ssname selectedObjects count) ) 
(terpri) 
(prompt (cdr (assoc © (entget ent)))) 
(setq count (1+ count) ) 


) 


(prompt (strcat "\nTotal objects processed: " (itoa count))) 


(princ) 


) 


8. Click File > Save. 
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If you are running AutoCAD on Mac OS, use the following steps to create an LSP file named 
acp_qs.lsp: 


1. In the Mac OS Finder, click Go > Applications. In the Finder window, double-click 
TextEdit. 


2. In TextEdit, click TextEdit > Preferences. In the Preferences dialog box, on the New 
Document tab click Plain Text and deselect Smart Quotes. Close the dialog box. 


3. Click File > New to create a plain ASCII text file. 


4. Click File > Save and type acp_qs. lsp in the Save As text box. On the sidebar at the left, 
click Documents or the MyCustomFiles folder that you created for the exercises and 
examples in this book. Click Save. 


5. If prompted to use the .1sp extension, click Use .Lsp. 


6. In the text editor area, type the following expressions. Replace the square brackets and 
the text inside them with the current date and your name. 


; Created [Today's date] by [Your name] - Quick Start Examples 
; Zoom shortcuts 

(defun c:ZE ( / ) (command "._zoom" "e")) 

(defun c:ZW ( / ) (command "._zoom" "w"') ) 


; Repeat Purge command 3 times to remove nested objects 
; and remove zero lines and empty objects 
(defun c:P3 ( / ) 


(repeat 3 
(command ",_-purge" ialt” Wei mon") 
) 
(command "._-purge" "_z") 
(command "._-purge" "_e") 


; List which objects are in a selection set 
(defun c:ListObjects ( / selectedObjects count ent) 
(prompt "\nSelect objects to list: ") 
(setq selectedObjects (ssget) 
count 0 


) 


(if (/= selectedObjects nil) 
(progn 
(while (> (sslength selectedObjects) count) 
(setq ent (ssname selectedObjects count) ) 
(terpri) 
(prompt (cdr (assoc © (entget ent)))) 
(setq count (1+ count) ) 


12 |CHAPTER1 QUICKSTART FOR NEW AUTOLISP PROGRAMMERS 


(prompt (strcat "\nTotal objects processed: " (itoa count))) 
) 
) 


(princ) 
) 
7. Click File menu > Save. 
The next exercise explains how to load the acp_qs. lsp file you created in the previous steps: 


1. Launch AutoCAD, or switch to AutoCAD if it is already running, and do one of the 


following: 
@ On the ribbon, click Manage tab > Customization panel > Load Application 
(Windows). 


@ On the menu bar, click Tools > Load Application (Mac OS). 
+ At the Command prompt, type appload and press Enter (Windows and Mac OS). 


2. When the Load/Unload Applications dialog box (see Figure 1.4) opens, browse to the 
Documents (or My Documents) folder or the MyCustomFiles folder, and select the 
acp_qs. lsp file. Click Load. 


If the File Loading - Security Concerns message box is displayed, click Load. 
Click Close to return to the drawing area. 


Draw some objects and create about three layers in your drawing. 


Bo ew 


At the Command prompt, type ze and press Enter. 

The drawing is zoomed to its extents. 

7. Type zwand press Enter. Specify the two corners of the window. 
The drawing is zoomed in based on the defined window. 


8. Type listobjects and press Enter. Select the objects to list and press Enter. Press F2 
on Windows or Fn-F2 on Mac OS to expand the command-line window (or open the 
AutoCAD Text Window on Windows). 


The object names of the selected objects are output to the command-line window. The 
following is sample output: 

LINE 

LWPOLYLINE 

CIRCLE 

CIRCLE 

Total objects processed: 4 


9. Type p3 and press Enter. The layers that you created in step 5, which are not being used 
in the drawing, should now have been removed. 
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In the previous exercise, you did the following: 


@ Created an LSP file to store AutoLISP expressions (see Chapter 10, “Authoring, Managing, 
and Loading AutoLISP Programs,” for more information) 


@ Loaded an LSP file into AutoCAD (see Chapter 10 for more information) 


Chapter 2 


Understanding AutoLISP 


The AutoLISP® programming language allows you to automate workflows in the Autodesk® 
AutoCAD® drawing environment. At first glance, AutoLISP can feel more than a bit intimidat- 
ing because of its syntax and use of parentheses. This is not an uncommon feeling for those who 
are new to AutoLISP and it’s why some claim that LISP stands for “Lost in Stupid Parentheses” 
instead of its true meaning, “LISt Processing.” Although AutoLISP and even programming in 
general can take time to learn and understand, venturing down a path that is often less traveled 
can prove to be the difference that makes you and the company you work for stand out 
from others. 

Here are some of the reasons I recommend AutoLISP: 


@ The programs can be entered directly at the AutoCAD Command prompt and can be used 
ina script or CUI/CUIx files. 


@ AutoLISP leverages your existing understanding of AutoCAD commands and 
system variables. 


@ AutoLISP programs can be executed on Windows or Mac OS with no changes based on the 
functions used. 


@ AutoLISP programs are low maintenance; programs written last week or even a decade 
ago often run with few to no changes in the latest release. 


Getting Started with AutoLISP 


I recommend that anyone who wants to create custom programs for AutoCAD consider 
AutoLISP as their first language to learn unless they have previous experience with another 
supported programming language, such as Visual Basic, VB.NET, C#, or C++. Even if you do 
know a programming language, you can use AutoLISP to quickly create a new custom program. 

AutoLISP was the first programming language I learned, and it took me a bit of time to grasp 
not only AutoLISP but general computation logic as well. However, once I got some traction with 
AutoLISP and programming concepts, things started to click for me. Even to this day, AutoLISP 
is still very near and dear to me as a programming option when it comes to creating custom pro- 
grams for AutoCAD. 
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When learning a programming language like AutoLISP, consider approaching it how you 
might learn a spoken language. First you need to learn some key fundamentals about the lan- 
guage and then spend time practicing to get good at it. As you start to learn AutoLISP, you will 
want to learn how to do the following: 


@ Construct an AutoLISP expression 

@ Execute an AutoLISP expression 

@ Select an environment to create and edit AutoLISP programs 
@ Store AutoLISP expressions in a file to reuse 


I have no doubt that with time and practice you too can be successful in leveraging AutoLISP 
to be more productive in your daily work. 


Understanding the Syntax of an Expression 
An AutoLISP expression is the formation of one or more items known as atoms. An atom 
represents a function or variable name, operator, or value. A valid AutoLISP expression must 
start with one of the following characters: 
(—Opening Parenthesis An opening parenthesis indicates the beginning of an AutoLISP 
expression and must be paired with a closing parenthesis [ ) ] to indicate the end of an 
AutoLISP expression. The opening and closing parentheses do not need to be on the same 
lines in an AutoLISP program, but each AutoLISP program must contain the same number of 
opening and closing parentheses. 
!—Exclamation Point An exclamation point is used to retrieve the current value assigned 
to a variable. The exclamation point must be placed in front of the variable’s name and can 
only be used at the AutoCAD Command prompt. I discuss variables later, in the “Storing and 
Retrieving Values” section. 


Table 2.1 shows various AutoLISP expressions and a description of what happens when the 
expression is evaluated at the AutoCAD Command prompt. 


TABLE 2.1: AutoLISP expressions 


EXPRESSION DESCRIPTION 


!cenPT Returns the current value of a user-defined variable named cenPT, which by default 
isnil. 


(setq cenPT Defines a user-defined variable named cenPT and assigns it a list that represents a 


'(5 5 0)) coordinate point of 5,5,0 in a drawing. 
(command Executes the AutoCAD circle command with the AutoLISP command function and 
"circle" draws a circle at the coordinate point assigned to the user-defined variable cenPT 


cenPT 6.25) witha radius of 6.25 units. 
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TABLE 2.1: AutoLISP expressions (CONTINUED) 
EXPRESSION DESCRIPTION 


(- 10 (/ 6 Returns a value of 8. When AutoLISP expressions are nested, the AutoLISP inter- 

3)) preter evaluates the innermost expression first. Then the next expression works its 
way to the outermost expression. (/ 6 3) is evaluated first and returns a value of 2. 
The outermost expression is then seen as being (- 10 2), which evaluates to the 
final value of 8. 


(setq msg The AutoLISP strcat function concatenates multiple string values into a single 
(strcat string value. The value of “Hello World!” is returned by the strcat function and 
"Hello " assigned to the user-defined variable msg. 

"World!")) 


Now that you have a basic understanding of what an AutoLISP expression looks like, the next 
step is to look at the inner workings of an AutoLISP expression’s structure. A valid AutoLISP 
expression must start with an opening parenthesis and end with a closing one. Typically, 
between the two parentheses you will find the atoms that should be evaluated; remember that 
an atom represents a function name and the values that a function should perform an action 
on. There are two exceptions to this, though. The first exception is an exclamation point, which 
I mentioned earlier. The other exception is when an apostrophe is used instead of the AutoLISP 
list function. Figure 2.1 explains the structure of an AutoLISP expression. 


FIGURE 2.1 Open Parenthesis — 
Argument — Argument — 
Structure of Starts pret | i String p Real 
an AutoLISP 
expression (command "._circle" (list 5 5 0) 6.25) 


Ends the AutoLISP 
Expression 


Function Name _| | L Closing Parenthesis — 
Argument — Nest 


Expression 


When you type an AutoLISP expression, make sure that you have at least one space between 
each atom. You can have more than one space, but at least one space must be present. A space 
lets AutoCAD know where the name of the function or operator ends and the first value (if one 
is provided) begins. The following expression demonstrates what happens when a space after an 
operator is missing; the space is missing after the / operator. 


(- 10 (/6 3)) 


When the function is evaluated by AutoLISP, it thinks you are trying to use a function named 
/6 instead of the / operator. You'll see this error: 


3 error: no function definition: 


/6 is displayed as a result of the missing space. 
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NOTE The AutoLISP programming language, unlike other popular programming languages such 
as C# or C++, is not case sensitive. This means that the functions and user-defined variables are 
evaluated in exactly the same way, regardless of how you enter them—uppercase, lowercase, 
or mixed case. For example, COMMAND and command have the same meaning. The only time case 
matters is when you're using string values, which must start and end with quotation marks ("). 


Executing Expressions 
AutoCAD supports a variety of ways to execute an AutoLISP expression. When first learn- 
ing AutoLISP, you'll find being able to enter an AutoLISP expression directly at the AutoCAD 
Command prompt a huge benefit; you can see in real time the results of an entered expres- 
sion. When you type an opening parenthesis or exclamation point at the Command prompt, 
AutoCAD passes control to the AutoLISP interpreter, which carries out the evaluation of the 
expression. After the expression is evaluated, control is then returned to AutoCAD and the 
standard Command prompt is displayed. 

The following exercise creates a circle with a center point of 5,5,0 and a radius of 6.25 units 
using AutoLISP expressions at the Command prompt: 


1. Launch AutoCAD, if it is not already running. 
2. At the AutoCAD Command prompt, type (setq cenPT '(5 5 0)) and press Enter. 


This defines a variable named cenPt and assigns it the coordinate value of 5,5,0. 
AutoLISP returns (5 5 0) to the Command prompt because the AutoLISP setq function 
returns the value it assigned to the variable. 


3. Type !cenPT and press Enter. 


4. Verify that the expected result, the value (5 5 0), is returned. If you see a value of nil, 
the expression you executed in step 2 was mistyped. Before continuing, repeat step 2 if a 
value of nil was returned. 


5. Type (command "._ circle" cenPt "6.25") and press Enter. 


The AutoLISP command function starts the circle command and draws a circle with a 
center point of 5,5,0 (or the current value assigned to the user-defined variable cenPt) and 
a radius of 6.25 units. I explain more about the command function in the section “Using the 
command Function” later in this chapter. 


6. Type (command "._zoom" "_e") and press Enter. 


The AutoLISP command function starts the zoom command and then uses the 
Extents option. 


NOTE = The exclamation point is required only when you want to see the current value assigned 
to a variable. As you saw in step 5, variables can be used in an AutoLISP expression without 
first entering an exclamation point. 
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In addition to executing AutoLISP expressions at the AutoCAD Command prompt, you can 
use the following: 


Scripts and Command Macros AutoLISP expressions can be used in script (SCR) files and 
command macros that are defined for use with a user-interface element in a customization 
(CUIx/CUI) file, just as you enter expressions at the Command prompt. I discussed SCR files in 
AutoCAD Platform Customization: User Interface and Beyond, Chapter 8, “Automating Repetitive 
Tasks,” and you learned about CUIx/CUI files in Chapter 5, “Customizing the AutoCAD User 
Interface for Windows,” and Chapter 6, “Customizing the AutoCAD User Interface for Mac.” 


A File You can store AutoLISP expressions in an ASCII text file and then load that file into 
AutoCAD. Entering expressions at the Command prompt is a great way to learn AutoLISP 
and is useful when only a few expressions need to be executed, but it is not ideal for com- 
plex programs or when you want to reuse the same expressions several times. I explain how 
to create and manage AutoLISP files in Chapter 10, “Authoring, Managing, and Loading 
AutoLISP Programs.” 


Accessing the AutoLISP Documentation 


The AutoLISP documentation is part of the AutoCAD Help system. The help system includes 
the AutoLISP Reference and AutoLISP Developer’s Guide topics. Although this book is designed 
to make it easy to learn the AutoLISP programming language and doubles as a reference that 
you can refer to time and time again when working with AutoLISP, it just is not possible to cover 
every function and technique here. 

The AutoLISP Reference topics explain what each function does in the AutoLISP program- 
ming language. The AutoLISP Developer’s Guide topics explore advanced techniques and fea- 
tures that are not covered in this book. 

You can see the AutoLISP documentation written for AutoCAD 2015 here: 


http: //help.autodesk.com/view/ACD/2015/ENU/ 


On the Autodesk AutoCAD 2015 Help landing page, click the Developer Home Page link. On 
the AutoCAD Developer Help Home Page, use the Function Listing (By Name And Feature) and 
AutoLISP Developer’s Topic Map links to access the AutoLISP documentation. The URL points 
to the AutoCAD 2015 on Windows documentation, but the AutoLISP documentation is designed 
for cross-platform development. 


Storing and Retrieving Values 


Programs—and programming languages, for that matter—are typically designed with one of 
two basic concepts in mind: to receive/consume or return/give. Most AutoLISP functions are 
designed to receive one or more values in the form of arguments, and then return a single value 
that can then be used by another function or returned to the user. When a function returns a 
value, you can store that value for future use—in the current custom function that is execut- 
ing or even between different AutoCAD sessions. After a value has been stored, you can then 
retrieve the value for use by your program when it is needed. 

You can store and retrieve values using these techniques: 
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User-Defined Variables User-defined variables allow you to temporarily store a value 
within a function or globally while a drawing remains open. A variable is defined using 

the AutoLISP setq function. For example, you can use the expression (setq msg "Hello 
AutoLISP! ") to define a variable named msg and assign it the text string “Hello AutoLISP!” I 
discuss user-defined variables in the next section. 


System Variables System variables store values that are often used to control the behavior 
of AutoCAD commands or the drawing environment, and even allow access to the 

values that are calculated by some AutoCAD commands, such as area or distance. Unlike 
with user-defined variables, you can’t create your own system variables. The system vari- 
able might represent a value that is stored in the current drawing or as part of the current 
AutoCAD user profile. See the section “Working with System Variables” later in this chapter. 


Environment Variables Similar to system variables, environment variables are used to 
control the behavior of AutoCAD commands or the drawing environment. You can access 
the values of environment variables that are defined by AutoCAD or even create your own as 
needed. Environment variables are stored as part of the AutoCAD user profile and as part of 
the Windows Registry or as a property list (Plist) file on Mac OS. I discuss accessing environ- 
ment variables later in this chapter in the “Accessing Environment Variables” section. 


Windows Registry (Windows Only) The Windows Registry is used to store settings that 
can be retrieved across different drawings and between application sessions. You can access 
the settings that AutoCAD reads and writes, and the Windows Registry is also a perfect 
place to store your own settings for your custom programs. I explain how to work with the 
Windows Registry in Chapter 8, “Working with the Operating System and External Files.” 


Property List File (Mac OS Only) Similar to the Windows Registry, Plist files are used to 
store settings that can be retrieved across different drawings and between application 
sessions. As with the Window Registry, you can access the settings that AutoCAD reads and 
writes, and the Plist files are also a perfect place to store your own settings for your custom 
programs. I explain in Chapter 8 how to work with the Plist files. 


Extended Data and Records Extended data (XData) and records (XRecords) allow you to 
attach custom information to a graphical object or create a custom dictionary in a drawing 
that can be used to store multiple entries containing custom information. XData is a great 
way to add unique information to an object in a drawing. AutoCAD uses XData to help 
facilitate dimension overrides, implement some multiline text features, and provide other 
features. You'll learn about XData in Chapter 6, “Creating and Modifying Graphical Objects, 
and XRecords in Chapter 7, “Creating and Modifying Nongraphical Objects.” 
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External Data Files AutoLISP allows you to write values to and read values from an 
ASCII text file that can be stored outside of AutoCAD on a local or network drive. I explain 
how to access external files in Chapter 8. If you are using Windows and have Microsoft 
Office installed, you can also access information that can be created and modified using 
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an application that is part of Microsoft Office—ActiveX/COM. I discuss using COM with 
AutoLISP in Chapter 12, “Working with ActiveX/COM Libraries (Windows only).” 


Configuration Files Configuration (CFG) files are used to store settings that can be 
retrieved across different drawings and between application sessions. Storing values in a 
CFG file is not as common as it once was, but you should be familiar with storing and 
retrieving values from a CFG file just in case you are working on an older program. I recom- 
mend using one of the other techniques for storing values that can be accessed across mul- 
tiple drawings or between application sessions, such as the Windows Registry, Plist files, or 
even external data files. You'll learn how to work with CFG files in Chapter 8. 


Setting and Using Variables 

In an AutoLISP program, it is not uncommon to want to use the same value more than once or to 
use a value returned by one function as a value for an argument in another function. Variables 
allow you to define a named location in memory to temporarily store a value. AutoLISP 
supports two types of variables: user-defined and predefined. 


@ User-defined variables are those that you or another developer create for use in an 
AutoLISP program. 


@ Predefined variables are those that are automatically defined and assigned a specific value 
by the AutoLISP environment for each drawing that is created or opened. 


DEFINING AND USING USER-DEFINED VARIABLES 


You can define a variable, called a user-defined variable, by using the AutoLISP setq function. 
By default each user-defined variable exists only in the context of the drawing in which it is 
defined; once the drawing is closed, the variable and its value are lost. 


NOTE [Ifyou need to retain the value assigned to a variable beyond the drawing it was defined 
in, consider using a custom dictionary object to store the value in a drawing, or use the Registry 
(Windows) or Plist file (Mac OS). I discussed these and other ways of storing values earlier, in 
the “Storing and Retrieving Values” section. 


The following shows the syntax of the setq function: 
(setq var_name value) 
var_name The var_name argument represents the name of the user-defined variable you 


want to define and assign a value to. 


value The value argument represents the data that you want to assign to the variable 
specified by the var_name argument. 
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The setq function always returns the value that is assigned to the last variable in the 
expression. 

The following AutoLISP expressions assign a coordinate value of 2,2,0 and numeric value of 
6.25 to user-defined variables named pt and dia: 


(setq pt '(2 2 0)) 
(setq dia 6.25) 


Although the setq function is commonly used to define a variable and then assign that 
variable a value, it can also be used to define multiple variable and value pairings. The following 
AutoLISP expression defines multiple variables and then assigns them a value: 


(setq pt '(2 2 0) 
dia 6.25) 


Once a variable has been defined and a value assigned, you can use it as an argument with 
another AutoLISP expression or return its current value at the AutoCAD Command prompt. 
There is nothing special you need to do in order to use a variable in an AutoLISP expression, but 
you need to include an exclamation point before the variable name in order to return its current 
value at the AutoCAD Command prompt. For example, to return the value of the variable dia at 
the AutoCAD Command prompt you would type !dia and press Enter. (The exclamation point 
isn’t necessary when you're using the variable inside an AutoLISP expression that begins and 
ends with parentheses.) 

The following exercise demonstrates how to define two variables and use their values at the 
AutoCAD Command prompt: 


1. At the AutoCAD Command prompt, type !cenpt and press Enter. 
nil should be returned, unless the variable was previously defined. 
2. Type (setq cenpt '(1 2 0)) and press Enter. 


The variable cenpt is defined and assigned the coordinate value 1,2,0. (1 2 @) is 
returned by the setq function. 


3. Type !cenpt and press Enter. 

The value of the cenpt variable is returned, which should be (1 2 0). 
4. Type (setq rad 3.125) and press Enter. 

The variable rad is defined and assigned the real numeric value 3.125. 
5. Type circle and press Enter. 

The circle command is started. 


6. Atthe Specify center point for circle or [3P/2P/Ttr (tan tan radius) ]: 
prompt, type !cenpt and press Enter. 


The value of the cenpt variable is returned and used for the circle’s center point. 
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7. Atthe Specify radius of circle or [Diameter]: prompt, type !rad and press Enter. 


The value of the rad variable is returned and used for the circle’s radius. The circle 
command ends and the circle is drawn. 


USING PREDEFINED VARIABLES 


In addition to the user-defined variables that you might create and use in AutoLISP expres- 
sions, the AutoLISP environment defines three variables that are assigned a specific value and 
are accessible from all drawing files that are opened. The variables that are predefined by the 
AutoLISP environment are as follows: 


PI The PI variable is assigned the value of 3.141592653589793, which is a constant value that 
represents the ratio of a circle’s diameter to its circumference. 


T The 7 variable always returns a value. This variable is commonly used when you test 
whether a condition returns True. 


PAUSE The PAUSE variable is assigned the string “\\”. The PAUSE variable is used in 
combination with the command function to suspend the execution of an AutoLISP expression 
and allow the user to respond to a command's request for input. 


WARNING Youshouldnever change the value ofa predefined variable; doing so could affect the 


execution of the AutoLISP programs that use them. 


CONTROLLING THE SCOPE OF A VARIABLE 


Variables can be accessed from the global or local scope of the AutoLISP environment. By 
default, all variables defined with the setq function are accessible globally. Each of the 
predefined variables that are defined by the AutoLISP environment are accessible from the 
global scope of the AutoLISP environment. However, you typically want to limit the number 
of such variables in the current drawing. Variables that are defined with the global scope con- 
tinue to consume system resources until you set the variable to the value of nil, whereas those 
defined as local variables have their system resources freed up when the execution of the func- 
tion in which they are defined ends. 

Another reason to limit global variables is what I refer to as unexpected data. Unexpected data 
occurs when a variable is assigned one value by your program and changed to another value 
by a different program. For example, say you assigned a global variable the value of 6.25, but 
another program (one written by you or even a third-party program) is using that same variable 
name and assigns the variable the value of (1 “A”). Based on how your program is designed, it 
might be using the variable as a way to persist the last value chosen by the user, much the same 
way the AutoCAD circle command remembers the last radius used. When your program goes 
to use the value, it gets a list instead of a numeric value, which must be handled differently and 
doesn’t even hold a value that is useful to you any longer. 
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UNIQUE FUNCTION AND GLOBAL VARIABLE NAMES 


AutoLISP is kind of like the Wild West—at times it can feel lawless since you have the ability to 
stake a claim to a name and still have someone come in and take it from you. For example, you 
can create a function named MakeLayer or a user-defined global variable named pt. A third party 
could do the same. If the third-party LSP file contains the same function or it defines a variable 
with the same name, your loaded function and defined variable are replaced. 


To help protect your functions and variables, I recommend adding a unique prefix to their names. 
Typically, the unique prefix you create is derived from a company name. For example, you might 
use the unique prefix of mc3 if your company was My Cool CAD Company. In addition to adding 
the unique prefix to a variable name, I recommend prefixing and suffixing the names of any global 
variables with an asterisk to make it easier to identify which variables are defined globally. 


Instead of creating a function named MakeLayer, you would use the name mc3_MakeLayer and for 
a variable named size (which might store the size of a bolt) you would use *mc3_size*. Another 
consideration when naming global variables is whether they need to be program or function specific. 
For function-specific global variables, consider including the name of the function that defines the 
variable. For example, the two functions DrawBolt and DrawScrew were originally written to use a 
global variable named *mc3_size*, which stores the recent size the user selects when using either 
of the functions. The size is then used the next time the function is executed; AutoLISP offers users 
their previous selection, which (based on the current naming of the variable) would be a potential 
problem. By using the variable names *mc3_drawbolt_size* and *mc3_drawscrew_size*, you 
ensure that both functions have their own global variable. 


The following explains the differences between global and local variables, and shows you 
how to define a variable in the local scope of a custom function: 


@ A global variable is accessible to all AutoLISP programs that are loaded into the drawing 
and to those expressions that are executed in the drawing from which the variable was 
defined. By default, all variables are defined with a global scope. 


@ A local variable is accessible only from the function in which it is defined. You define the 
variable using the setq function, but the name of the variable is also added to the local_var 
argument of the defun function to restrict its use to just that function. I discuss the defun 
function later in this chapter in the section “Defining and Using Custom Functions.” If a 
variable is not added to this argument, it remains a global variable. 


Although a variable can be defined with a global scope, a variable with the same name can 
exist in the local scope of a function. When this happens, the expressions inside your function 
are aware only of the local variable. The following steps show how a variable defined in the 
local scope of a custom function takes precedence over a variable defined with a global scope: 


1. At the AutoCAD Command prompt, type the following and press Enter: 
(setq *apc_var* "Global") 
2. Type the following and press Enter to define the GLobalVar function: 


(defun c:GlobalVar ( / )(alert *apc_var*) ) 
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3. Type the following and press Enter to define the LocalVar function: 


(defun c:LocalVar ( / *apc_var™*) 
(setq *apc_var* "Local") 
(alert *apc_var*) 


) 


4. Type globalvar and press Enter. Click OK to exit the alert message box. 


The alert message box displays the text string assigned to the *apc_var* variable in the 
global scope, which is the value Global. 


5. Type localvar and press Enter. Click OK to exit the alert message box. 


The variable *apc_var* is assigned the value of the string "Local" and then an alert mes- 
sage box displays the text string assigned to the *apc_var* variable in the local scope, 
which is the value Local. 


6. Type globalvar and press Enter. Click OK to exit the alert message box. 


The alert message box displays the text string assigned to the *apc_var* variable in the 
global scope, which is the value Global. When the localvar function was executed in 
step 5, the*apc_var* variable was assigned a value that existed only while the function 
was executing; it did not overwrite the value of the globally defined *apc_var* variable. 


TIP User-defined variables are normally accessible only from the drawing in which they are 
defined, but you can use the AutoLISP vl-bb-ref and vl-bb-set functions to define variables 
on what is known as the blackboard. The blackboard is a centralized location for defining variables 
that can be accessed from any open drawing. The AutoLISP vl-propagate function can also 
be used to define a variable with a specific value in all open drawings and any drawings that 
are subsequently opened in the AutoCAD session. You can learn more about these functions in 
the AutoCAD Help system. 


Working with System Variables 

System variables are used to alter the way commands work, describe the current state of a draw- 
ing or AutoCAD environment, and even specify where the support files are for your custom 
programs. Many of the settings that are exposed by system variables are associated with 
controls in dialog boxes and palettes; other settings are associated with various command 
options. For example, many of the settings in the Options (Windows) or Application Preferences 
(Mac OS) dialog box are accessible from system variables and even environment variables 
(which I discuss in the next section). 

A system variable can store any one of the basic data types that AutoLISP supports (see 
“Exploring Data Types” later in this chapter). You can see the hundreds of system variables and 
the type of data each system variable holds by using the AutoCAD Help system. Whereas you 
might normally use the setvar command to list or change the value of a system variable at the 
AutoCAD Command prompt, with AutoLISP you use the getvar and setvar functions to query 
and set the value of a system variable. 
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Here’s the syntax of the getvar and setvar functions: 


(getvar sysvar_name) 
(setvar sysvar_name value) 


sysvar_name The sysvar_name argument represents the name of the system variable you 
want to query or set. 


value The value argument represents the data that you want to assign to the 
system variable. 


The next exercise demonstrates how to query and set the value of the osmode system variable, 


which controls the running object snap drafting aid. This setting is available in the Drafting 
Settings dialog box (dsettings command). 


1. At the AutoCAD Command prompt, type (setq *apc_cur_osmode* (getvar 
"osmode") ) and press Enter. 


The function returns the current value of the osmode system variable and assigns it to the 
user-defined variable *apc_cur_osmode* with the setq function. 


2. Type (setvar "osmode" 33) and press Enter. The osmode system variable is assigned 
the integer value of 33, which represents the Endpoint and Intersection running object 
snap modes. 


3. Type osnap and press Enter. In the Drafting Settings dialog box, select the Object Snap 
tab and verify that the Endpoint and Intersection options are checked and all other 
options are unchecked. Click Cancel to return to the Command prompt. 


4. Type (setvar "osmode" *apc_cur_osmode*) and press Enter. 
The previous value of the system variable is restored. 


5. Type osnap and press Enter. In the Drafting Settings dialog box, you will notice that the 
options checked will represent those of the restored running object snap settings value. 
Click Cancel to return to the Command prompt. 


TIP The AutoCAD Help system is a great resource for learning about system variables. However, 


if you need to support multiple AutoCAD releases you will need to reference the documenta- 
tion for each release. To make it easier to identify which system variables are supported in the 
recent and past AutoCAD releases, I created a list of system variables that spans a large number 
of AutoCAD releases; you can view the list here: www. hyperpics.com/system_variables/. 


Accessing Environment Variables 


Environment variables allow you to access settings that are, at times, accessible only from the 
Options (Windows) or Application Preferences (Mac OS) dialog box and not through system 
variables or from the Command prompt. Unlike with system variables, though, there is no 
official documentation that explains which environment variables are available or what values 
they can be assigned. 


Many of the environment variables that Iam aware of can be found stored in the 


Windows Registry or a Plist file on Mac OS. Both of these storage locations include a General 
Configurations section for the AutoCAD program, and it is in this section that you will find the 
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environment variables you can manipulate. You use the AutoLISP getenv and setenv functions 
to retrieve and set the value of an environment variable. 


WARNING Unlike system variables, environment variable names are case sensitive. For 
example, MaxHatchis not the same as maxhatch or MAXHATCH. 


The following shows the syntax of the getenv and setenv functions: 


(getenv envvar_name) 
(setenv envvar_name "value”) 


envvar_name The envvar_name argument represents the name of the environment variable 
you want to query or set. 


value The value argument represents the string value that you want to assign to the envi- 
ronment variable. Environment variables can only be assigned a string value, but that string 
could contain a number or even a list of values. 


Both the getenv and setenv functions return the current value of the environment variable 
or the value that was successfully assigned to an environment variable. 

The following steps show how to retrieve and set the value of the DefaultFormatForSave 
environment variable, which controls the default format for saving drawings. This setting is 
available in the Options dialog box on Windows, but not in the Application Preferences dialog 
box on AutoCAD 2013 and earlier on Mac OS. It does affect the behavior of saving a drawing file 
on both Windows and Mac OS. 


1. At the AutoCAD Command prompt, type (setq *apc_cur_val* (getenv 
"DefaultFormatForSave") ) and press Enter. 


The function returns the current value of the environment variable and assigns it to the 
user-defined variable *apc_cur_val* with the setq function. 


2. Type (setenv "DefaultFormatForSave" "48") and press Enter. 


The DefaultFormatForSave environment variable is assigned the value of 48, which 
represents the AutoCAD 2010 drawing file format. If you are using an earlier release, you 
may need to use a different value to set a previous drawing file format as current. 


3. Type saveas and press Enter. In the SaveAs dialog box, notice that the Files Of Type 
drop-down list will list AutoCAD 2010/LT2010 Drawing (*.dwg) as the current option. 
Click Cancel to return to the Command prompt. 


4. Type (setenv "DefaultFormatForSave" *apc_cur_val*) and press Enter. 
The previous value of the environment variable is restored. 


5. Type saveas and press Enter. In the SaveAs dialog box, notice that the Files Of Type 
drop-down list now lists the previous default drawing file format. Click Cancel to return 
to the Command prompt. 


TIP I created a list (though not complete or up to date) of the environment variables available 
in a number of earlier releases of AutoCAD. You can find this list here: 


http://www. hyperpics.com/downloads/resources/customization/autolisp/AutoCAD%20 
Environment%20Variables.pdf 
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Exploring Data Types 

Programming languages use data types to help you identify the following: 
@ The type of data required by a function’s argument 
@ The type of data that might be returned by a function 


AutoLISP on Windows and Mac OS support the following data types: 


Integer An integer is a numeric value without a decimal point. The numeric value must be 
in the range of —32,768 to 32,767 and can be optionally prefixed with a plus sign (+) for posi- 
tive numbers. You can use an integer value to represent an angular or linear distance or the 
number of columns or rows in an array or table, or to specify whether a system variable is 
enabled or disabled. Examples include -10, 0, 1, +45, and 400. You'll learn about using inte- 
ger values with mathematical functions in Chapter 3, “Calculating and Working 

with Values.” 


Real A real value is numeric with a decimal point. The numeric value must be in the range 
of 1.80 x 10° to -4.94 x 10°” for negative numbers and 4.94 x 10 to 1.80 x 10° for positive 
numbers. A positive number can optionally be prefixed with a plus sign and be expressed in 
exponential notation; 10e4 is the same as 100000.0. When using a value between -1.0 and 1.0, 
you must use a leading zero before the decimal; .5 is not a valid real number but 0.5 is. You 
might use a real number to represent an angular or linear distance or part of a coordinate. 
Examples of a real number are -10.01, 0.0, 1.125, +45.0, and 400.00001. Chapter 3 
discusses using real values with mathematical functions. 


NOTE The real data type in AutoLISP is commonly referred to as a double or float in other 
programming languages. 


String A string is a value that contains one or more characters enclosed in quotation marks. 
You might use a string value for a command or system variable name, a file path and name, 
messages and prompts that are displayed to the user, or even a real or integer number 
converted to a string. Examples of a string value are “Hello AutoLISP!","._line", "\ 


nSpecify next point: ",and "6.25". You'll learn more about working with string values 
in Chapter 3. 


List A list is an expression of one or more atoms enclosed in parentheses. All AutoLISP 
expressions are known as lists, but lists often represent 2D points, 3D points, and data 
groupings. Examples of a list are (1.5 2.75), (1.5 2.75 0.5), ("Model" "Layout1" 
"Layout2"), (1 "A" 2 "B"),and (). () represents an empty list. When you're assigning 

a list to a variable, either the list must be preceded by an apostrophe, asin (setq pt '(1 2 
0)), or you must use the AutoLISP list function, asin (setq pt (list 1 2 0)). 
Chapter 4, “Working with Lists,” explores creating and manipulating lists. 


NOTE The list data type in AutoLISP is similar to an array in other programming languages. 


Dotted Pair A dotted pair is a list of two values separated by a period. Dotted pairs are 
commonly used to represent property values for an object. The first value of a dotted pair 
is sometimes referred to as a DXF group code. For example, (40 .2.0) represents the radius of 
a circle; DXF group code value 40 indicates the radius property, and 2.0 is the actual radius 
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value for the circle. When you're assigning a dotted pair to a variable, either the pair must be 
preceded by an apostrophe, as in (setq dxf_40 '(40 . 2)),or you must use the AutoLISP 
cons function, as in (setq dxf_40 (cons 40 2)). You'll learn more about creating and 
manipulating dotted pairs in Chapter 6. 


Entity Name An entity name is an in-memory numeric label used to reference an object 
stored in a drawing. You will often work with an entity name to modify an object’s proper- 
ties or after a request to select objects in a drawing has been completed. See Chapters 6 and 7 
to learn how to work with entity names. 


AutoLISP on Windows supports a few additional data types, and I discuss these additional 
data types in depth and how they are used in Chapter 12. The data types that are specifically 
used for working with ActiveX libraries are as follows: 


VLA-Object A VLA-Object represents an ActiveX object that is used when working with 
methods and properties imported from the AutoCAD Object Library or another ActiveX 
library. An ActiveX object can be an object stored in a drawing, an open drawing, or the 
AutoCAD application itself. 


Variant A variant is a generic data type that can hold any type of data supported by the 
Component Object Model (COM) interface. 


Safearray A safearray is not really a data type, but rather a data structure that can contain 
multiple values similar to the list data type. You use a safearray when you need to repre- 
sent a coordinate value, specify the objects used to define a closed boundary when creat- 
ing a Region or Hatch object, or specify the data types and values that make up the XData 
attached to 

an object. 


You can use the AutoLISP type function to identify the type of data retuned by a function or 
assigned to a variable. The following shows the syntax of the type function: 


(type value) 


value The value argument represents any valid atom; an AutoLISP expression, a value, or 
a variable. 


The type function returns a symbol that can be used to determine if the value returned by a 
function or assigned to a variable is the type of data you are expecting. The following AutoLISP 
expressions define a custom function named IsString, which uses the type function to deter- 
mine whether a value is of the string data type: 


(defun IsString (val / ) 
(if (= (type val) 'STR) T nil) 
) 


You can use the IsString function by entering it at the AutoCAD Command prompt or 
loading it as part of an AutoLISP (LSP) file. When the function is executed, it will return T if the 
value it is passed is a string data type or nil for all other data types. The following shows sev- 
eral examples of the IsString function along with the values they return: 


(IsString "2") 
T 
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(IsString 2) 
nil 


(IsString PAUSE) 
T 


(IsString PI) 
nil 


Leveraging AutoCAD and Third-Party Commands 


The AutoLISP command and command-s functions allow you to leverage the functionality of 

a standard AutoCAD command or a command defined by a loaded third-party application. 
Because these functions allow you to use a command, they are often some of the first functions 
that many new to AutoLISP learn. 


NOTE When using the command and command-s functions, keep in mind that the command 
being executed in most cases behaves similar to when you use it from the AutoCAD Command 
prompt. That means you can use many system variables to control a command’s behavior or 
outcome. For example, you can use the c layer system variable to set a layer as current be- 
fore an object is drawn or even disable running object snaps with the osmode system variable 
before using the Line and circle commands. After you make a call to the last command and 
command-s function in your AutoLISP programs, be sure to restore any changed system vari- 
ables to their previous values. 


In Chapters 5 and 6 in AutoCAD Platform Customization: User Interface and Beyond, you learned 
about creating command macros. Some of the special characters used in command macros also 
apply to the command and command-s functions. Table 2.2 lists the special characters that can pre- 
fix a command name. 


TABLE 2.2: Special characters that can prefix a command name 


SPECIAL CHARACTER DESCRIPTION 


. (period) Accesses an AutoCAD command’s standard definition even when a command 
might have been undefined with the undef ine command. 


_ (underscore) Instructs AutoCAD to use the global command name or option value instead of 
the localized name or value provided. This allows the macro to function as 
expected when used with a different language of the AutoCAD release. 
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Using the command Function 

The command function passes each argument it receives to the AutoCAD Command prompt. The 
first argument is the name of the command to execute. After the command name are the argu- 
ments that reflect the options and values that should be executed by the command. If a com- 
mand is already active when the command function is evaluated, the arguments are passed to the 
current command. 


TIP Before using the command function, you should test to see if a command is active by query- 
ing the current value of the cmdactive system variable with the AutoLISP getvar function. A 
value greater than 0 indicates a command is active. You can issue the command function without 
any arguments to simulate pressing Esc to get to a clean Command prompt. 


The following shows the syntax of the command function: 


(command [cmdname [argN ...]]) 


cmdname The cmdname argument represents the name of the command to execute. cmdname 
is optional. 


argN The argN argument represents the options and values that should be executed at 
the AutoCAD Command prompt. argN is optional. Arguments are also known as command 
tokens. 


The following AutoLISP example assigns the coordinate values of 2,2,0 and 5,6,0 to the user- 
defined variables named *apc_pt1* and *apc_pt2* The line command is then used to draw 
a line between the coordinate values assigned to the user-defined variables *apc_pt1* and 
*apc_pt2*. 


(setq *apc_pt1* '(2 2 0) 
*apc_pt2* '(5 6 0)) 
(command "._line" *apc_pt1* *apc_pt2* "") 


NOTE = The arguments that you might pass to the command function can span multiple expres- 
sions. The following produces the same results as the previous AutoLISP example code: 


(setq *apc_pt1* '(2 2 0) 
*apc_pt2* '(5 6 0)) 

(command "._line") 

(command *apc_pt1l* *apc_pt2* "") 


When the command function is used, you can suspend the execution of an AutoLISP program 
and allow the user to provide input at the Command prompt. You use the predefined PAUSE 
variable or the "\\" ASCII character sequence to allow the user to provide a value. The follow- 
ing AutoLISP expression starts the circle command and then allows the user to specify a cen- 
ter point. Once a center point is specified, the circle’s diameter is set to 3 units. 


(command "._circle" PAUSE "_d" 3) 
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CONTROLLING A COMMAND’S VERSION 


Internally each standard AutoCAD command is assigned a new version number when a change is made 
that affects an AutoLISP program, script, or command macro. You use the initcommandversion 
function to control which version of a command is used by the next use of the command or command-s 
function. The ini tcommandversion function doesn’t require a value, but when one is provided it must 
be an integer value that represents the version of the command you want to use. 


The following example uses version 1 of the color command: 


(initcommandversion 1) 
(command "._color") 


Version 1 of the color command displays options at the Command prompt; version 2 or later 
displays the Select Color dialog box instead. The -insert command is another command that is 
affected by the initcommandversion function. When using version 2 of the -insert command, 
the user can interact with the AutoCAD Properties palette in Windows while a preview of the block 
is being dragged in the drawing area. 


Using the command-s Function 


The command-s function is similar to the command function, with a few differences. Like the 
command function, the command-s function passes each argument it receives to the AutoCAD 
Command prompt. The first argument that is passed to the command-s function is the name of 
the command you want to execute. This is followed by the arguments that reflect the options 
and values you want executed. 

When you use the command-s function, you must supply all values to complete the command 
that you want to execute. Unlike with the command function, you can’t do either of these things: 


@ Suspend the execution of an AutoLISP program and allow the user to provide input at the 
Command prompt with the predefined PAUSE variable. 


@ Start the execution of a command in one expression and finish the command in another 
expression. The following is not a valid use of the command-s function: 


(command-s "._circle") 
(command-s '(5 5) 2) 


The following shows the syntax of the command-s function: 


(command-s [cmdname [argN ...]]) 


cmdname The cmdname argument represents the name of the command to execute. 
cmdname is optional. 


argN The argN argument represents the options and values that should be executed at the 
AutoCAD Command prompt. argN is optional. Arguments are also known as command 
tokens. 


DEFINING AND USING CUSTOM FUNCTIONS 


The following AutoLISP example assigns the coordinate value of 5,5,0 to the user-defined 
variable named *apc_cpt*. The circle command is then used to draw a circle using the coordi- 
nate value assigned to the user-defined variables *apc_cpt* and a radius of 5. 


(setq *apc_cpt* '(5 5 0)) 
(command-s "._circle" *apc_cpt* 5) 


Working with Commands That Display a Dialog Box 

When using the command and command-s functions, avoid commands that display a dialog box 
because doing so can lead to inconsistencies when your AutoLISP program is executed. Instead, 
you should use the alternative command-line equivalent of a command, or use the system and 
environment variables that might be changed with the dialog box. In most cases, adding a 
hyphen (-) in front of a command that normally displays a dialog box will cause the command 
to display a series of command prompts instead. For more information, see AutoCAD Platform 
Customization: User Interface and Beyond, Chapter 8, or the AutoCAD Help system. 

If you need to use the dialog box that a command normally displays, you must use the 
AutoLISP initdia function. This function indicates to AutoCAD that the next command 
executed with the command or command-s function should display a dialog box, if it is supported. 
Using the initdia function before a command that doesn’t display a dialog box has no effect on 
the command. The initdia function doesn’t accept any arguments. 

The following exercise demonstrates how the initdia function affects the use of the command 
function when using the plot command: 


1. At the AutoCAD Command prompt, type (command "._plot") and press Enter. 


The plot command starts and the Detailed plot configuration? [Yes/No] <No>: 
prompt is displayed. 


2. Press Esc to end the plot command. 
3. Type (initdia) and press Enter. 


It will seem like nothing happens, but rest assured a flag has been set in the background 
for AutoCAD to check with the next use of the command function. 


4. Type (command "._plot") and press Enter. 
The plot command starts and the Plot dialog box is displayed. 
5. When the Plot dialog box opens, click Cancel. 


Defining and Using Custom Functions 


Although you can execute AutoLISP expressions one at a time at the Command prompt, doing 
so makes it hard to repeat or use more than a few AutoLISP expressions at a time. You can 
group AutoLISP expressions together into a new custom function and then execute all of the 
expressions in the group by using the function name you specify. 
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Defining a Custom Function 
The AutoLISP defun function is used to define a custom function. A custom function defined 
with defun behaves similar to a standard AutoLISP function, but it can also mimic a command 
that can be entered directly at the AutoCAD Command prompt or used in a script or command 
macro. Typically, a function is defined when you want to make it easier to execute and repeat a 
specific set of AutoLISP expressions. 

The following shows the syntax of the defun function that you should follow when defining 
a function that doesn’t need to mimic an AutoCAD command: 


(defun function_name ([argN] / [local_varN]) 
expressionN 


) 


function_name The function_name argument represents the name of the function you 
want to define. 


argN The argN argument represents a list of arguments that the function can accept and 
then act upon. argN is optional. 

local_varN The local_varN argument represents a list of user-defined variables defined 
in the function that should be restricted to the local scope of the function. local_varN is 
optional. Variables defined within a function have a global scope if they aren’t added to the 
local_varN argument. 


expressionN The expressionN argument represents the AutoLISP expressions that should 
be executed by the function when it is used. 


The following shows the syntax of the defun function when you want to define a function 
that can be accessed from the AutoCAD Command prompt, similar to a standard AutoCAD 
command: 


(defun c:function_name ( / [local_varN]) 
expressionN 


) 


NOTE Custom functions that have the C: prefix shouldn’t accept any arguments. If your 
function requires any values, those values should be requested from the user with the getxxx 
functions. Chapter 5, “Requesting Input and Using Conditional and Looping Expressions,” dis- 
cusses getting input from the user. 


The following steps show how to define two custom functions: a function named dtr that 
converts an angular value in degrees to radians, and another named c: zw, which executes the 
zoom command with the Window option. These functions can be executed at the AutoCAD 
Command prompt. 


1. At the AutoCAD Command prompt, type (defun dtr (deg / ) and press Enter. 


The defun function defines a function named dtr, which accepts a single argument 
named deg. In this example the dtr function will use no local user-defined variables, but 
if you decided to, you'd list them after the forward slash. 
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Type (* deg (/ PI 180)) and press Enter. 


The value assigned to the variable PI will be divided by 180 and then multiplied by the 
value passed into the dtr function that is assigned to the deg variable. 


Type ) and press Enter. 


The AutoLISP interpreter returns the name of the function that is defined; in this case 
DTR is returned. This parenthesis closes the AutoLISP expression that was started with 
the defun function. 


Type (dtr 45) and press Enter. 
The value 0.785398 is returned. 
Type (defun c:zw ( / ) and press Enter. 


The defun function defines a function named zw and it is prefixed with C:, indicating 
it can be entered at the AutoCAD Command prompt. This function doesn’t accept any 
arguments and there are no variables that should be limited locally to this function. 


Type (command "._zoom" "_w")) and press Enter. 


The AutoLISP interpreter returns C:ZW. The AutoLISP expression that uses the command 
function will be executed when the zw function is used. The command function starts the 
zoom command and then uses the Window option. The last closing parenthesis ends the 
AutoLISP expression that was started with the defun function. 


Type zw and press Enter. 


You will be prompted to specify the corners of the window in which the drawing should 
be zoomed. 


Using a Custom Function 

After you define a custom AutoLISP function with the defun function, you can execute it at 
either the AutoCAD Command prompt or from an AutoLISP program. Chapter 10 discusses cre- 
ating AutoLISP programs. In the previous section, you defined two functions: dtr and 

c:zw. The following rules explain how you can execute a custom AutoLISP function defined 
with the defun function: 


+ 


If a function name does not have the C: prefix, you must place the name of the function 
and any arguments that it accepts between opening and closing parentheses. It doesn’t 
matter whether you are calling the function from the AutoCAD Command prompt or an 
AutoLISP program. For example, to call the dtr function defined in the previous section 
you would use (dtr 45) to call the dtr function with an argument value of 45. 


If a function name has the C: prefix, you can enter the name of the function directly at the 
AutoCAD Command prompt without entering the C: prefix first. However, if you want to 
use a function that has the C: prefix from an AutoLISP program, you don’t use the command 
or command-s function since it is not a true, natively defined AutoCAD command. Instead 
you must place the name of the function along with the C: prefix between opening and 
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closing parentheses. For example, to call the C: ZW function defined in the previous section 
you would use (c:zw). 


@ Functions used ina script or command macro for a user-interface element must follow the 
same syntax that can be entered at the AutoCAD Command prompt. 


TIP Although custom AutoLISP functions that have the C: prefix aren't recognized as native 
AutoCAD commands, you can use the AutoLISP vlax-add-cmd and vlax-remove-cmd func- 
tions to register a custom AutoLISP function as a built-in AutoCAD command. (These functions 
are available only on Windows.) There are a couple reasons you might want to do so. The first 
is so that your custom functions trigger events or reactors related to when a command starts 
or ends. The other reason is so that your custom function can be called with the command or 
command-s function. You can learn more about these functions in the AutoCAD Help system. 


Example: Drawing a Rectangle 


I don’t introduce any new functions or techniques in this section, but I want to explain how to 
use many of the AutoLISP functions explored in this chapter to define a custom function that 

creates a new layer and draws a rectangle. I will break down each AutoLISP expression of the 

function in more detail in Table 2.3. 


1. Create anew AutoCAD drawing. 
2. At the AutoCAD Command prompt, type the following and press Enter after each line: 


(defun c:drawplate ( / old_osmode ptl pt2 pt3 pt4) 
(setq old_osmode (getvar "osmode")) 
(setvar "osmode" 0) 
(command "._-layer" "_m" "Plate" "_c" 5 "™ »w) 
(setq pt1 '(0 0 0)) 
(setq pt2 '(5 0 0)) 
(setq pt3 '(5 2.75 0)) 
(setq pt4 '(0 2.75 0)) 
(command "._line" ptl pt2 pt3 pt4 "_c") 
(setvar "osmode" old_osmode) 


The drawplate function draws a rectangle that is 5 x 2.75 units in size, starting at the 
coordinate 0,0,0. 


3. Type drawplate and press Enter. 


Once the drawplate function completes, you'll have a rectangular object made up of four 
line segments on a new layer named Plate; see Figure 2.2. 


FIGURE 2.2 

Result of the 
drawplate custom 
function 


EXAMPLE: DRAWING A RECTANGLE 


4. Create anew AutoCAD drawing. 


5. At the AutoCAD Command prompt, type drawplate and press Enter. 


The message Unknown command "DRAWPLATE". Press F1 for help. is displayed. This 
message is the expected result because AutoLISP entered or loaded into one drawing is 


accessible only to that drawing. Chapter 10 shows you how to create and load AutoLISP files. 


Now that you have seen the drawplate function in action, Table 2.3 provides a breakdown of 
what each expression is doing in the function. 


TABLE 2.3: 


EXPRESSION 


(defun 
c:drawplate 
( / old_ 
osmode pt1 
pt2 pt3 pt4) 


(setq old_ 
osmode 
(getvar 
"osmode") ) 


(setvar 
"osmode" 0) 


(command 
",_-layer" 

" m" "Plate" 
" c" 5 we 


wm) 


(setq pt1 
'(0 © 0)) 


(setq pt2 
'(5 0 0)) 


(setq pt3 
'(5 2.75 0)) 


(setq pt4 
'(0 2.75 0)) 


AutoLISP expressions used to define the drawplate function 


DESCRIPTION 


Uses the de fun function to define the custom function draw- 
plate, which has the prefix C: and can be executed directly at the 
AutoCAD Command prompt. The argument list of the de fun func- 
tion is empty because a function that can be entered directly at the 
Command prompt should not accept arguments. The forward slash 
character separates the argument and local variable lists. The local 
variable list contains five variables; these variables are added to the 
list so they aren't defined as global variables. 


Assigns the current value of the osmode system variable to the 
variable named old_osmode. 


Sets the osmode system variable to a value of 0. 


Executes the - Layer command with the Make option to create a 
layer with the name Plate. Once the layer is created (or if it already 
existed), the Make option sets the layer as current. The layer is also 
assigned the AutoCAD Color Index (ACI) value of 5. 


Assigns a list of three values that represent the coordinate value 
0,0,0 to the variable named pt1. 


Assigns a list of three values that represent the coordinate value 
5,0,0 to the variable named pt2. 


Assigns a list of three values that represent the coordinate value 
5,2.75,0 to the variable named pt3. 


Assigns a list of three values that represent the coordinate value 
0,2.75,0 to the variable named pt4. 
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TABLE 2.3: AutoLISP expressions used to define the drawplate function (CONTINUED) 
EXPRESSION DESCRIPTION 
(command "._ Executes the Line command and uses the values assigned to the 
line" pt1 variables pt1, pt2, pt3, and pt4 to draw three sides of a rectangle. 
pt2 pt3 pt4 Once the first three segments are drawing, the Close option draws 
te!) the fourth and final line segment to create a closed object. 
(setvar Sets the osmode system variable to the current value of the old_ 
"osmode" osmode variable. 


old_osmode) 


) Closes the defun function. 


Chapter 3 


Calculating and Working with 
Values 


Many of the standard AutoCAD® commands perform a lot of calculations as they are used from 
the user interface, but much of this work is shifted to you as a programmer when you work 
with AutoLISP®. AutoLISP supports a variety of functions that allow you to perform basic and 
complex math calculations, manipulate numeric or string values, and work with the elements 
contained in a list. I cover working with lists in Chapter 4, “Working with Lists.” 

Although many of the math and data-manipulation functions in AutoLISP provide a solid 
foundation for working with values, you might need to combine many of these functions to 
create custom functions that return a value. In Chapter 2, “Understanding AutoLISP,” you 
learned how to create custom functions, but I didn’t explain how to return a value like standard 
AutoLISP functions do. Later in this chapter, we'll explore how to define a custom function that 
returns a value using the defun function. 


Calculating Values with Math Functions 


When working with AutoCAD, you must consider the accuracy with which objects are placed 
and the precision with which objects are created in a drawing. The same is true with AutoLISP; 
you must consider both accuracy and precision when creating and modifying objects. The 
AutoLISP math functions allow you to perform a variety of basic and complex calculations. 
You can add or multiply numbers together, or even calculate the sine or arctangent of an angle. 


Performing Basic Math Calculations 


When manipulating geometric properties of an object in a drawing, you often need to perform a 
math operation on the current value of an object and then assign that value back to the object— 
or even apply it to another object. Using math operations, you can manipulate an object’s loca- 
tion, decrease a text object’s height, increase an object’s length or radius, and much more. The 
basic math functions that AutoLISP supports allow you to 


@ Add, subtract, multiply, or divide numbers 
Get the remainder after dividing two numbers 
Calculate bitwise values 


Get the minimum or maximum value in a range of values 


+% ¢ ¢ ¢ 


Determine if a value is 0 or negative 
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This exercise demonstrates how to add and subtract values in AutoLISP: 

1. At the AutoCAD Command prompt, type (setq sum (+ 2 3 0.5 4)) and press Enter. 
All the values are added together for a final value of 9.5. 

2. Type (setq val (+ 2 (1- sum))) and press Enter. 


1 is subtracted from the value assigned to the sum user-defined variable, for a value of 8.5. 
Then, 2 is added to the value of 8.5 for a final value of 10.5, which is assigned to the val 
user-defined variable. 


3. Type (command "._circle" PAUSE val) and press Enter. 


The AutoLISP command function starts the circle command and then prompts for a 
center point. After you provide a center point, the current value of the val user-defined 
variable is used for the radius of the circle. 


4. Atthe Specify radius of circle or [Diameter]: prompt, pick a point in the draw- 
ing area. 


The new circle is drawn. 


ADDING AND SUBTRACTING NUMERIC VALUES 


Adding and subtracting numbers in AutoLISP works just like you might have learned in ele- 
mentary school, with one slight difference: Instead of placing a + or - operator symbol between 
each number as you normally would, the AutoLISP + or - function must be the first atom in a 
list. An atom is an element or item within a list. The + and - functions can add or subtract any 
number of integer or real numeric values, and they return an integer or real numeric value. An 
integer is returned when all the values passed to the function are integers; otherwise, a real 
value is returned. 

The following shows the syntax of the + and - functions: 


(+ [numberN ...]) 
(- [numberN ...]) 


The numberN argument represents the numeric values you want to add together or subtract 
from each other. The numberN argument is optional and can be more than one value. If no value 
is passed to the + or - functions, 0 is returned. 

Here are some examples of adding and subtracting numbers with the + and - functions, 
along with the values that are returned: 


(+ 5 2 3) 

10 

(+ 5.0 2 3) 

10.0 

(+ 5.0 2.25 0.25) 
7.5 

(- 2 3) 


CALCULATING VALUES WITH MATH FUNCTIONS 


-1 
(+ (- 1.625 0.125) 1) 
2.5 


In addition to the + and - functions, you can use the 1+ function to increment (or 1- to 
decrement) a value by 1. If you need to increment or decrement a value by more than 1, you will 
need to use the + and - functions. The 1+ and 1- functions are a great way to create a counter in 
a looping expression. I explain how to use looping expressions in Chapter 5, “Requesting Input 
and Using Conditional and Looping Expressions.” 

The following shows the syntax of the 1+ and 1- functions: 


(1+ number) 
(1- number) 


The number argument represents the numeric value that should be incremented or decre- 


mented by 1. 
Here are examples of incrementing or decrementing a number with the 1+ and 1- functions, 
along with the values that are returned: 


(setq cnt 0) 


0 

(1+ cnt) 
1 

(1- cnt) 
=I 


MULTIPLYING AND DIVIDING NUMERIC VALUES 


Multiplying and dividing numeric values is an effective way to calculate a new scale factor 

to increase or decrease the scale factor of an object, or even to figure out how many objects of 

a specific size might fit into an area or along a linear path. Use the * function to multiply any 
number of integer or real numeric values and return the resulting product. Using the / function 
returns the quotient after dividing any number of numeric values. The * and / functions return 
an integer or real numeric value. An integer is returned by the functions when all the values 
passed to the function are integers; otherwise, a real numeric value is returned. 


NOTE Ifyou divide several integer values, the value returned is an integer even if the returned 
value would normally have a remainder. Use at least one real number with the / function to 
return a real number with the remainder. 


The following shows the syntax of the * and / functions: 


(* [numberN ...]) 
(/ [numberN ...]) 


The numberN argument represents the numeric values you want to multiply or divide by each 
other. The numberN argument is optional and can be more than one value. If no value is passed 
to the * or / function, 0 is returned. 
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Here are examples of multiplying and dividing numbers with the * and / functions, along 
with the values that are returned: 


(* 5 3) 

15 

(* 5.0 2 3) 
30.0 

(/ 5 2) 

2 

(/ 5.0 2) 
2.5 


NOTE Dividing a number by 0 causes an error and returns this message: ; error: divide 
by zero. If the error is not handled, the custom function that contains the error is terminated. 
You can use the vL-catch-all-apply function to keep the function from being terminated 
I discuss the v_-catch-all-apply function in Chapter 9, “Catching and Handling Errors.” 


When dividing numbers, you can use the AutoLISP rem function to return the remainder of 
the first number after it has been divided by all the other numbers supplied to the function. The 
rem function can take any number of numeric values; the function returns 0 when no values are 
passed to it. The following demonstrates the rem function: 


(/ 10.0 3) 
3.33333 

(rem 10.0 3.0) 
1.0 


AutoLISP includes a function named gcd that can be used to return the greatest common 
denominator of two integer values. The gcd function requires two integer values, and it returns 
an integer that represents the greatest common denominator of the provided values. Here are 
two examples: 


(gcd 5 2) 

2 

(gcd 54 81) 
27 


UsING OTHER BASIc MATH FUNCTIONS 


Most of your math function needs should be met with the basic math functions that I previ- 
ously covered, but you should be aware of some other basic math functions. These other func- 
tions allow you to get the minimum or maximum number in a range of values or determine if a 
numeric value is equal to 0 or is negative. 

The following explains some of the other basic math functions that are available as part of 
AutoLISP: 


min and max The min and max functions accept any integer or real numeric values. The min 
function returns the smallest numeric value from those that are passed to it, whereas the max 
function returns the largest numeric value. A real value is returned by the function, except 
when the function is passed only integer values—in that case, an integer value is returned. If 
no numeric value is passed to either function, 0 is returned. 
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The following are examples of the min and max functions: 


(min 9 1 1976 0.25 100 -25) 


-25.0 

(max 9 1 1976 0.25 100 -25) 
1976.0 

(max 9 1 1976 100 -25) 
1976 


minusp and zerop The minusp and zerop functions accept an integer or real numeric value. 
The minusp function returns T if the value that it was passed is negative, or it returns nil if 
the value was positive. The zerop function also returns T or nil; T is returned if the value 
passed is equal to 0. The zerop function can help you avoid dividing a number by 0 or seeing 
if a system variable is set to 0. 


The following are examples of the minusp and zerop functions: 


(minusp 25) 
nil 

(minusp -25) 
T 

(zerop 25) 
nil 

(zerop 0) 

T 


For more information on the minusp and zerop functions, see the AutoCAD Help system. 


Performing Advanced Math Calculations 

In addition to basic math functions, AutoLISP offers a range of advanced math functions that 
aren't used as frequently. These advanced functions allow you to work with angular, exponen- 
tial, natural logarithm, or square root numeric values. AutoLISP supports the advanced math 
functions listed in Table 3.1. 


TABLE 3.1: AutoLISP advanced math functions 
FUNCTION DESCRIPTION 
sin Returns the sine of an angular value expressed in radians. 
atan Calculates the arctangent of an angular value expressed in radians. 
cos Returns the cosine of an angular value expressed in radians. 
exp Returns a numeric value that has been raised to its natural antilogarithm. 
expt Returns a numeric value after it has been raised by a specified power. 
log Calculates the natural logarithm of a numeric value. 


sqrt Gets the square root of a numeric value. 
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For more information on these functions, see the AutoCAD Help system. 


Working with Bitwise Operations 

Integer values can be used to represent what is known as a bit pattern or bit-coded value. A bit- 
coded value is the sum of one or more bits. A bit is a binary value; when one or more bits are 
combined they create a unique sum. AutoCAD uses bit-coded values for many different object 
properties (DXF group codes) and system variables. 

For example, the layer status property (DXF group code 70) of a layer is a bit-coded value that 
contains various flags used to specify whether the layer is frozen (1 bit), locked (4 bit), or depen- 
dent on an xref (16 bit). The osmode system variable is another example of a bit-coded value in 
AutoCAD. In the osmode system variable, the value indicates which running object snaps are 
currently enabled. Refer to the AutoCAD Help system to determine whether an object property 
or system variable is an integer or bit-coded value. 

Because a bit-coded value is represented by the integer data type, you can use the + and — 
functions to add or remove a bit value for the overall sum of a bit-coded value. AutoLISP also 
provides several useful functions that you can use when working with bit-coded values. The 
logior and logand functions help combine several bit-coded values and determine whether a 
bit is part of a bit-coded value. Let’s take a closer look at the Llogior and logand functions. 


LOGIOR 


The logior function allows you to combine several bits into a single bit-coded value and 
ensures that a bit is added only once to the resulting bit-coded value. Although you can use the 
+ function to add several bits together, that function simply adds several values together and 
returns the resulting value, which might return a bit-coded value with a different meaning. For 
example, the bits 1 and 4 are equal to the bit-coded value of 5: 


; Final result is a bit-coded value of the bits 1 and 4 
(logior 1 4) 


5 

; Final result is an integer of 5 
(+ 1 4) 

5 


Adding the bits 1, 2, and 5 with the Logior function results in the bit-coded value of 7. 


; Final result is a bit-coded value of the bits 1, 2, and 4 
(logior 1 2 5) 
7 


Were you expecting a value of 8 maybe? The 1 bit is added only once because the logior 
function recognizes that the 1 bit is provided individually and as part of the bit-coded value of 
5 in the previous example. If you were to add the same numbers (1, 2, and 5) together with the + 
function, the result would be 8 and would mean something different. A value of 8 is a bit in and 
of itself. 


; Final result is an integer of 8 and not a bit-coded value of the bits 1, 2, and 
4 

(+ 12 5) 

8 
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Here is the syntax of the lLogior function: 
(logior [bitN ...]) 


The bitN argument represents the bits you want to combine. If no bit is passed to the func- 
tion, 0 is returned. 

The following examples add the provided bits together into a bit-coded value of 35 with the 
logior function. The bits 1, 2, and 32 represent the ENDpoint, MIDpoint, and INTersection 
running object snap settings. The second expression returns a value of 35 as well, and because 
3 is a bit-coded value that represents both bits 1 and 2, the Logior function will add a bit only 
once to the bit-coded value it returns. If you used the + function instead, it would be easy to add 
a bit more than once to a bit-coded value. 


; Returns the sum of the bits 1, 2, and 32 
(setq new_osmode (logior 1 2 32)) 

35 

; Returns the sum of the bits 1, 2, 3, and 32 

; Bit 3 is a bit-coded value containing 1 and 2 
(logior 1 2 3 32) 

35 


LOGAND 


The logand function is used to determine whether a specific bit or bit-coded value is part of 
another bit-coded value. This type of comparison in a program can be helpful when you need to 
handle specific conditions in the AutoCAD environment, such as making sure that the current 
layer is not frozen or locked when you're creating or selecting objects, or making sure a specific 
running object snap is set. 

Here is the syntax of the Logand function: 


(logand [bitN ...]) 


The bitN argument represents the bits you want to test for comparison. If no value is passed 
to the function, 0 is returned. 

The following examples use the logand function to determine if a bit is common with the 
provided bits or bit-coded values. Bit 2 represents the MIDpoint running object snap; a bit-coded 
value of 12 represents the CENter and QUAdrant running object snaps; and the bit-coded value 
of 34 represents the running object snaps MIDpoint and INTersection. The first example returns 
0 because the bit 2 value is not part of the bit-coded value 12 (bit codes 4 and 8), whereas 2 is 
returned for the second example because bit 2 is part of the bit-coded value of 34 (bit codes 1, 2, 
and 32). 


; Returns © because no bit codes are in 

; common with the two numbers 

(logand 2 12) 

(0) 

; Returns 2 because it is the common bit code 
; in common with both numbers 

(logand 2 34) 

2s 
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If you want to add or remove a bit to or from a bit-coded value, you can use logand to verify 
whether a bit is already part of the bit-coded value. If 0 is returned by Logand, the bit code is 
not part of the bit-coded value, so the bit could safely be added with the + function. If the bit is 
returned instead of 0, the bit is part of the bit-coded value and can be safely removed using the 
- function. 


OTHER BITWISE FUNCTIONS 


In addition to the AutoLISP logior and logand functions, you can use these functions when 
working with bit-coded values: 


~ (Bitwise NOT) The~ (bitwise NOT) function accepts a bit (integer) value and converts 
it into a binary number before performing a bitwise negation. The negation changes any 1 

in the binary value to a 0, and any 0 to a 1. For example, an integer value of 32 expressed as a 
binary value is as follows: 


0000 0000 0000 0000 0000 0000 0000 0000 
0000 0000 0000 0000 0000 0000 0010 0000 


The binary value is read from lower right to upper left. 


When the ~ (bitwise NOT) function is applied to a bit value of 32, it becomes a bit value of -33 
and is expressed as the binary value 


LIIL MIA TLIN TALL: IIIN. AIALA LLLI LLLE 
1111 1111 1111 1114 1111 1111 1101 1111 


The following is an example of the ~ (bitwise NOT) function: 


(~ 32) 
-33 


boole The AutoLISP boole function is used to perform a Boolean operation on two bit- 
coded (integer) values. The Boolean operations that can be performed are AND (1), XOR (6), 
OR (7), and NOR (8). For example, the AND Boolean operation can be used to see which bits 
are common between two bit-coded values. If an AND Boolean operation is performed on 
the bit-coded values 55 and 4135, a bit-coded value of 39 is returned. 


The following is an example of the boole function: 


(boole 1 55 4135) 
39 


lsh The AutoLISP lsh function accepts a bit (integer) value and converts it into a binary 
number before performing a bitwise shift by a specified number of bits. For example, you can 
shift the bit value of 1 by 3 bits to return the 8 bit value. A bit value of 1 is expressed as the 
binary value 1000 0000 (read left to right); the bitwise shift moves the 1 three bits to the right 
and it becomes a binary value of 0001 0000, or a bit value of 8. 


The following is an example of the lsh function: 


(lsh 1 3) 
8 
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For more information on the ~ (bitwise NOT), boole, and lsh functions, see the AutoCAD 
Help system. 


WORKING WITH BIT-CODED VALUES 


The following exercise demonstrates how to work with bit-coded values. You'll create a custom 
function that allows you to toggle the state of the INTersection object snap. The current running 
object snap modes are stored in the osmode system variable, which contains a bit-coded value. 
The INTersection object snap is represented by the bit code 32. 


1. 


At the AutoCAD Command prompt, type (setq cur_osmode (getvar "osmode")) and 
press Enter. 


The current value of the osmode system variable is assigned to the cur_osmode user- 
defined variable. 


Type (logand 32 cur_osmode) and press Enter. 


The value 32 or 0 is returned. If 32 is returned, then the INTersection object snap mode is 
enabled. 


3. Type osnap and press Enter. 


When the Drafting Settings dialog box opens, verify the current state of the Intersection 
check box based on the results you got in step 2. Click Cancel. 


If 32 is returned by the logand function in step 2, the Intersection check box should be 
checked; otherwise it will be unchecked. 


Type the following and press Enter: 


(defun c:ToggleINT ( / cur_osmode) 
(setq cur_osmode (getvar "osmode") ) 


(if (= (logand 32 cur_osmode) 0) 
(setvar "osmode" (logior 32 cur_osmode) ) 
(setvar "osmode" (- cur_osmode 32)) 


) 
(princ) 


) 


Type toggleint and press Enter. 


The custom function checks the bit-coded value of the osmode system variable to see if bit 
code 32 is part of the value. If bit code 32 is not part of the bit-coded value, 32 is added to 
the current value of the osmode system variable with the logior function. Otherwise, 32 
is subtracted from the osmode system variable. 


Open the Drafting Settings dialog box and verify that the state of the Intersection check 
box has been changed. Click Cancel. 


Type toggleint and press Enter. 


The previous state of the INTersection object snap mode is restored. 
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Manipulating Strings 


Strings are used for a variety of purposes in AutoLISP, from displaying command prompts and 
messages to creating annotations in a drawing. The string values in an AutoLISP program can 
have a static or fixed value that never changes during execution, or a value that is more dynamic 
and is changed by the use of string-manipulation functions. You can manipulate a string by 


+ ¢ ¢ © © ¢ 


Concatenating two or more strings together 

Getting the number of characters or their position in a string 
Replacing characters in a string 

Removing characters from or truncating a string 

Trimming empty spaces or other characters from the ends of a string 


Changing the case of and evaluating the values of a string 


This exercise demonstrates how to concatenate and manipulate strings in AutoLISP: 


1. 


At the AutoCAD Command prompt, type (setq str1 "String:") and press Enter. 
The string “String:” is assigned to the str1 user-defined variable. 
Type (setq str2 "\"Sample\"") and press Enter. 


nn 


The string “\’Sample\’” is assigned to the str2 user-defined variable. 
Type (setq mtlinel (strcat stri " " str2)) and press Enter. 


A new string value of “String: ’Sample\”” is returned and assigned to the mtlinel user- 
defined variable. 


Type (setq mtline2 (strcat "Length: " (itoa (strlen str2)))) and press Enter. 


A new string value of “Length: 8” is returned and assigned to the mtline2 user-defined 
variable. 


Type (command "mtext" PAUSE PAUSE (strcat mtlinel "\\P" mtline2) "") and 
press Enter. 


The mtext command is started and you are prompted for the two corners of the multiline 
text boundary. 


At the Specify first corner: prompt, pick a point in the drawing. 


7. Atthe Specify opposite corner or [Height/Justify/Line spacing/Rotation/ 


FIGURE 3.1 
Multiline text 
object created 
from multiple 
string values 


Style/Width/Columns]: prompt, pick a point in the drawing. 


The new multiline text object is created and should look like Figure 3.1. 


String: "Sample" 
Length: 8 


MANIPULATING STRINGS| 49 


I discuss the strcat and strlen functions in the following sections, along with many other 
functions related to working with strings. The section “Converting Data Types” later in this 
chapter explores the itoa function used to convert an integer to a string. 


Concatenating Strings 

Two or more strings can be concatenated (combined) into a string value that can then be pre- 
sented to the user or used by another function. There are many different reasons why you might 
combine two or more strings. Some of the most common reasons follow: 


+ To define an absolute file location based on a path and filename 
@ To write a string value out toa file 


@ To create a prompt based ona fixed string value and a recently entered string or numeric 
value that was converted to a string 


@ Tobuilda field or multiline text value using special characters that can then be displayed 
using an MText object 


The AutoLISP strcat (short for string concatenation) function is used to concatenate multiple 
strings together. The following shows the syntax of the strcat function: 


(strcat [stringN ...]) 


The stringN argument represents the strings that should be concatenated together to form 
the resulting string. The stringN argument is optional. If no argument is provided, an empty 
string represented by a pair of quotation marks (“”) is returned. 

The following demonstrates the strcat function and the values that are returned: 


(setq str1 "Hello" str2 "AutoLISP!") 

(strcat str1 str2) 

"HelloAutoLISP!" 

(strcat str1 " from " str2) 

"Hello from AutoLISP!" 

(setq kwd1 "Plate" kwd2 "Bolt" *prev_kwd* "Plate") 

(strcat "\nEnter object to place [" kwd1 "/" kwd2 "] <" *prev_kwd* ">: ") 
"\nEnter object to place [Plate/Bolt] <Plate>: " 


Getting the Length of and Searching for Strings 


When working with strings, you may want to know the number of characters in a string or the 

position in which a text pattern begins. You can use the length of a string to make sure a string 

doesn’t exceed a specific number of characters, to remove characters from the end of a string, or 
to insert a string at a known location. 


RETURNING THE LENGTH OF A STRING 


The AutoLISP strlen (short for string length) function returns the number of characters in a 
string. The following shows the syntax of the strlen function: 


(strlen [string]) 
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The string argument represents the string for which you want to know the length; the 
length is returned as an integer. Spaces in a string are counted as one character. The string 
argument is optional, and a length of 0 is returned if no argument is provided. 

The following are examples of the strlen function and the values that are returned: 


(strlen "Hello") 


5 

(strlen " Hello ") 

9 

(strlen "Product: %product%") 
18 


SEARCHING FOR A TEXT PATTERN IN A STRING 
In addition to wanting to know the number of characters in a string, you might want to know if 
a specific text pattern is contained in a string. This can be helpful if you want to create a custom 
find and replace program for text contained in an annotation object. The AutoLISP vl-string- 
search function takes a text pattern and compares that pattern to a string. The position at which 
the text pattern begins in the string is returned as an integer. If the text pattern is not found, 
nil is returned. The first character in a string is located in the 0 position. A string can contain 
multiple instances of the text pattern, but the v_-string-search function only returns the start 
position of the first instance of the text pattern. 

The following shows the syntax of the v_-string-search function: 


(vl-string-search pattern string [start]) 


The arguments are as follows: 


pattern The pattern argument represents the text pattern that you want to search for in 
the string argument. The text pattern is case sensitive. 

string The string argument represents the string that you want to search. 

start The start argument represents the starting position in the string argument where 
you want to begin searching for the text pattern specified by the pattern argument. The start 
argument is optional. If no argument is provided, searching for the text pattern starts at the 0 
position. 


The following are examples of the vl-string-search function and the values that are 
returned: 


(vl-string-search "product" "Product: %product%"') 
g 


10 

(vl-string-search "Product" "Product: %product%") 
(0) 

(vl-string-search "program" "Product: %product%") 
nil 


Although the vl-string-search function can be used to search a string for a text pattern, 
the function is limited to searching only for that text pattern and in the case specified. If you 
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have a need to search a string for multiple text patterns, the vl-string-search function is not 
very efficient by itself. You can use the wcmatch (short for wildcard match) function to help 
search a string for more complex text patterns with the use of wildcard pattern matching. 

However, unlike the vl-string-search function, the wcmatch function returns T only if 
the wildcard pattern matches part or all of the string; otherwise, nil is returned if no match is 
found. If a match is found, it is up to you to try to find the text in the string that was matched. 
You can use the AutoLISP substr function along with a looping expression to get down to the 
substring that is a match. You'll learn more about the substr function in the “Replacing and 
Trimming Strings” section later in this chapter, and more about looping expressions in 
Chapter 5. 

The following shows the syntax of the wcmatch function: 


(wematch string pattern) 


The arguments are as follows: 
string The string argument represents the string that you want to search. 


pattern The pattern argument represents the wildcard text pattern that you want to 
search for in the string argument. For information on the wildcard characters that are sup- 
ported, see the “wcmatch” topic in the AutoCAD Help system. 


Here are examples of the wcmatch function and the values that are returned: 


(wematch "W6X12" "W#X12") 

T 

(wcmatch "wW*6" "W#X12") 

nil 

The AutoLISP strlen, vl-string-search, and wcmatch functions are all helpful in learning 


more about the length or characters in a string. Here are two additional functions that can be 
useful in finding out what characters are in a string: 


vl-string-position 
Returns the position of a character in a string 
vl-string-mismatch 


Returns the length of the characters that are at the beginning of and in common between two 
strings 


For more information on these functions, see the AutoCAD Help system. 


Replacing and Trimming Strings 

In the previous section, I mentioned how the vl-string-search and wcmatch functions can be 
used to determine whether a text pattern exists in a string. After you know that the text pattern 
is in a string, you can use that information to split a string into two strings based on the text 
pattern’s location, replace a matching text pattern with a new string, or remove the string that 
matches a text pattern. Along with working with a string based on the results of a matched text 
pattern, you can trim spaces or specific characters off the ends of a string. 
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REPLACING A TEXT PATTERN IN A STRING 


A text pattern or set of characters in a string can be replaced with a new string or set of char- 
acters, making it easy to update an out-of-date part number or even a basic implementation 
of inline variable expansion. For additional information on inline variable expansion, see the 
“What Is Inline Variable Expansion?” sidebar. 


WHAT Is INLINE VARIABLE EXPANSION? 


Inline variable expansion is the process of defining a variable and then adding the name of the vari- 
able using the format %VARIABLE_NAME% (Windows) or ${VARIABLE_NAME} (Mac OS) ina string. 
The name of the variable is then replaced with the variable’s actual value when the expression con- 
taining the string is used. Inline variable expansion is not native functionality in AutoLISP, but it can 
be simulated. Inline variable expansion is supported by other programming languages and is often 
used with values that are defined by the operating system. Listing 3.1 in this section demonstrates 
one possible implementation of inline variable expansion in AutoLISP. 


The AutoLISP vl-string-subst (short for string substitution) function is commonly used to 
replace a text pattern in a string. Only the first instance of the matching text pattern is replaced, 
so you might need to run the vl-string-subst function several times on a string. 

The following shows the syntax of the vl-string-subst function: 


(vl-string-subst new_string pattern string [start]) 
The arguments are as follows: 


new_string The new_string argument represents the string that you want to use as the 
replacement value if the text pattern specified by the pattern argument is found in the 
string argument. 


pattern The pattern argument represents the text pattern that you want to search for in 
the string argument. 


string The string argument represents the string that you want to search. 


start The start argument represents the starting position in the string argument that 
you want to begin searching for the text pattern specified by the pattern argument. The 
start argument is optional. If no argument is provided, searching for the text pattern starts 
at the first position. 


The following are examples of the vl-string-subst function and the values that are 
returned: 


(vl-string-subst "career" "hobby" "Programming is my hobby.") 
"Programming is my career." 

(vl-string-subst "_" " " "Project 123 - ABC") 

"Project_123 - ABC" 


Listing 3.1 is a custom function that mimics the use of inline variable expansion. When the 
function is executed, it attempts to match the text between % (percent) signs with a user-defined 
variable. If the variable is found, the inline variable is replaced by its current value. 
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LISTING 3.1: The ExpandVariable function 


; Custom implementation of expanding variables in AutoLISP 
5 To use: 
; 1. Define a variable with the setq function. 
; 2. Add the variable name with % symbols on both sides of the variable name. 
5 For example, the variable named *program* would appear as %*program*% 
; in the string. 
; 3. Use the function on the string that contains the variable. 
(defun expandvariable (string / strTemp) 
(while (wematch string "*%*%*") 
(progn 

(setq start_pos (1+ (vl-string-search "%" string) )) 

(setq next_pos (vl-string-search "%" string start_pos) ) 

(setq var2expand (substr string start_pos (- (+ next_pos 2) start_pos))) 


(setq expand_var (vl-princ-to-string 
(eval (read (vl-string-trim "%" var2expand) )))) 


(if (/= expand_var nil) 
(setq string (vl-string-subst expand_var var2expand string) ) 


) 


string 


) 


; Define a global variable and string to expand 
(setq *program* (getvar "PROGRAM") 
str2expand "PI=%PI% Program=%*program*%" 


; Execute the custom function to expand the variables defined in the string 
(expandvariable str2expand) 
"PT=3.14159 Program=acad" 


Along with the vl-string-subst function, you can use the v_-string-translate function 
to replace all instances of a character anywhere in a string with another character. Since the 
vl-string-translate function works with single characters, it provides much less control over 
using a text pattern that contains multiple characters. 

The following example demonstrates how the vl-string-translate function can be used to 
replace all of the spaces in a string with underscores: 


(vl-string-translate " " "_" "Project 123 - ABC") 
"Project_123_-_ABC" 


For more information on the vl-string-translate function, see the AutoCAD Help system. 
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TRIMMING A STRING 


A string can be trimmed to a specific length by specifying a starting position and the number 
of characters to keep, resulting in what is known as a substring. The AutoLISP substr (short for 
substring) function allows you to keep a set of characters from a given string. 

The following shows the syntax of the substr function: 


(substr string start [length]) 


The arguments are as follows: 


string The string argument represents the string that contains the substring you want to 
return. 


start The start argument represents the starting position in the string argument that the 
substring begins. A string starts at the first position. 


length The length argument represents the number of characters the substring should 
contain. The length argument is optional. If no argument is provided, the substring contains 
all of the characters from the starting position specified by the start argument to the end of 
the string. 


The following are examples of the substr function and the values that are returned: 


(substr "Programming is my hobby." 12) 

" is my hobby." 

(substr "Programming is my hobby." 1 11) 
"Programming" 

(substr "Programming is my hobby." 19 5) 
"hobby" 


Although the substr function is very helpful in pulling a string apart, it is not the most effi- 
cient function to use if you need to remove or trim specific characters from the left or right ends 
of a string. The AutoLISP vl-string-trim, vl-string-left-trim, and vl-string-right- 
trim functions are better suited to trimming specific characters, such as extra spaces or zeroes, 
from the ends of a string. The vl-string-trim function trims both ends of a string, whereas the 
vl-string-left-trimand vl-string-right-trim functions trim only the left and right ends 
of a string, respectively. Characters that are part of the character_set argument are trimmed 
from the respective ends of the string until a character that isn’t a part of the character_set 
argument is encountered. 

The following shows the syntax of the v_-string-trim, vl-string-left-trim, and vl- 
string-right-trim functions: 


(vl-string-trim character_set string) 
(vl-string-left-trim character_set string) 
(vl-string-right-trim character_set string) 


The arguments are as follows: 


character_set The character_set argument represents the characters on the end or ends 
of the string specified by the string argument that should be trimmed off. 
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string The string argument represents the string that should be trimmed based on the 
characters specified by the character_set argument. 


The following are examples of the vl-string-trim, vl-string-right-trimand vl- 
string-left-trim, functions and the values that are returned: 


(vl-string-trim " " " Extra spaces ") 

"Extra spaces" 

(vl-string-right-trim " .0" "Trailing Zeroes and Spaces 0.10000 ") 
"Trailing Zeroes and Spaces 0.1" 

(vl-string-right-trim " .0" "Trailing Zeroes and Spaces 1.0000 ") 
"Trailing Zeroes and Spaces 1" 

(vl-string-left-trim " 0" " 001005 Leading Zeroes and Spaces") 
"1005 Leading Zeroes and Spaces" 


Changing the Case of a String 
The text in most annotation objects of a drawing file is in all uppercase letters. However, the text 
that a user might enter at a Command prompt might be in uppercase, lowercase, or even mixed- 
case letters. The AutoLISP strcase (short for string case) function can be used to convert all of 
the letters in a string to either uppercase or lowercase. 

The following shows the syntax of the strcase function: 


(strcase string [lowercase]) 


The arguments are as follows: 


string The string argument represents the string that you want to convert to all upper- 
case or lowercase letters. 


lowercase The lowercase argument, when provided, indicates that all the letters should 
be converted to lowercase. T is typically provided as the value for this argument. Using a 
value of T indicates that the string argument should be converted to all lowercase letters. 


The following are examples of the strcase function and the values that are returned: 


(setq str_convert "StRiNg") 
(strcase str_convert) 
"STRING" 

(strcase str_convert T) 
"string" 


The strcase function can't be used to convert specific letters of a string to sentence or title 
case. However, if you need that type of functionality, you can use the subst and strcase func- 
tions to do get the desired results. For example, in the case of wanting to convert a string to sen- 
tence case, you can use the substr function to get the first character of a string and then get the 
remaining characters of a string. After you get the two parts of the string you can then change 
their case with the strcase function and concatenate the two strings back together with the 
strcat function. 
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Listing 3.2 is an example of a custom AutoLISP function that could be used to convert a text 
string to sentence case. 


LISTING 3.2: The sentencecase function 


; Converts a string to sentence case 
3 (sentencecase "string") 
(defun sentencecase (string / ) 
(strcat (strcase (substr string 1 1)) 
(strcase (substr string 2 (1- (strlen string))) T) 


(sentencecase "THIS IS A SAMPLE SENTENCE."') 
"This is a sample sentence." 


Evaluating Values to Strings 


When working with strings, you may also want to concatenate a numeric value as part of 

a prompt string or response to the user. Before you can concatenate a nonstring value to a 
string, you must convert the nonstring value to a string. The quickest way to do so is to use the 
AutoLISP vl-princ-to-string and vl-prini-to-string functions. 

The difference between the two functions is how quotation marks, backslashes, and other 
control characters are represented in the string that is returned. The vl-prinl-to-string 
function expands all control characters, whereas the vl-princ-to-string function doesn't. 
For more information on control characters that can be used in strings, search on the keywords 
“control characters” in the AutoCAD Help system. 

The following shows the syntax of the vl-princ-to-string and vl-prini-to-string 
functions: 


(vl-princ-to-string atom) 
(vl-prini-to-string atom) 


The atom argument represents the expression, variable, or value that should be converted to 
and returned as a string. 

The following are examples of the v_-princ-to-string and vl-prini-to-string func- 
tions, and the values that are returned: 


(vl-princ-to-string 1.25) 

W256" 

(vl-princ-to-string (findfile (strcat (getvar "PROGRAM") ".exe"))) 
"C:\\Program Files\\Autodesk\\AutoCAD 2014\\acad.exe" 
(vl-prini-to-string 1.25) 

W125" 

(vl-prini-to-string (findfile (strcat (getvar "PROGRAM") ".exe"))) 
"\"c:\\\\Program Files\\\\Autodesk\\\\AutoCAD 2014\\\\acad.exe\"" 


I discuss other AutoLISP functions that can be used to convert nonstring values to strings 
and strings to nonstring values next. 
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Converting Data Types 


Variables in AutoLISP aren't defined to hold a specific data type, which allows the variable to be 
flexible and hold any valid type of data. However, data types are used by AutoLISP as a way to 
enforce data integrity and communicate the types of values an argument expects or a function 
might return. As your programs become more complex and you start requesting input from the 
user, there will be times when a function returns a value of one data type and you want to use 
that value with a function that expects a different data type. 

I explained the use of the v_-princ-to-string and vl-prini-to-string functions earlier, 
but those functions simply convert most values to a string. AutoLISP also contains many other 
conversion functions that allow you to convert the following: 


@ Numeric values to strings 

@ Strings to numeric values 

@ Numeric values to other number types 
@ Lists to strings and strings to lists 


You'll learn how to convert lists to strings and strings to lists in Chapter 4. 


Converting Numeric Values to Strings 
Numbers are the most commonly used data type in AutoLISP because you are often working 
with the size of any object, positioning an object in a drawing, or counting objects to generate 
a bill of materials. The reason you might want to convert a numeric value to a string is to add a 
value to a prompt string, create a text string for an annotation object, or write a value out to an 
external file. 

Table 3.2 lists the available functions for converting a numeric value to a string. 


TABLE 3.2: AutoLISP functions for converting numeric values to strings 


FUNCTION DESCRIPTION 


angtos The angtos function accepts a numeric value, integer or real number, which represents an 
angle in radians. Optionally, you can specify the unit that the angle should be converted 
into along with a precision. The function returns a string based on the angular value, unit, 
and precision arguments specified. You can use the AutoLISP angtof function to reverse 


the conversion. 


rtos The rtos function accepts a numeric value, integer or real number, which represents a dis- 
tance. Optionally, you can specify the linear unit that the distance should be converted into 
along with a precision. The function returns a string based on the linear value, unit, and 
precision arguments specified. You can use the AutoLISP atof function to reverse the 


conversion. 
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TABLE 3.2: AutoLISP functions for converting numeric values to strings (CONTINUED) 


FUNCTION DESCRIPTION 


itoa The itoa function accepts an integer and returns a string value of the converted integer 
value. If a real number is passed to the function, the ; error: bad argument type: 
fixnump: error message is displayed. You can use the AutoLISP atoi function to reverse 
the conversion. 


chr The chr function accepts an ASCII code, which is an integer value, and returns the character 
equivalent of the ASCII code value. If a real number is passed to the function, the ; error: 
bad argument type: fixnump: error message is displayed. You can use the AutoLISP 
ascii function to reverse the conversion. 


The following are examples of the angtos, rtos, itoa, and chr functions, and the values they 
return: 


(angtos (/ PI 2)) 
Nog" 

(angtos (/ PI 6) 0 5) 
"30.00000" 

(rtos 1.375) 
"1.3750" 

(rtos 1.375 4) 

"m al 3/8\" "m 

(rtos 1.375 3 4) 
"1.3750\"" 

(itoa -25) 

"25" 

(itoa 5) 

wow 

(chr 32) 

wow 

(chr 65) 

"A" 


For more information on these functions, see the AutoCAD Help system. 


Converting Strings to Numeric Values 

You can use string values for prompts and messages to the user, as you saw earlier. You can 
store string values with annotation objects, and you can also read a part number from an 
external data file and assign that value to an attribute in a block. Even though a string value is 
between quotation marks, it can still represent a numeric value. Before you use a string that con- 
tains a number with a function that expects a numeric value, you must convert that string to a 
numeric value. 
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Table 3.3 lists the AutoLISP functions that can be used to convert a string to a numeric value. 


TABLE 3.3: AutoLISP functions for converting strings to numeric values 
FUNCTION DESCRIPTION 
angtof Accepts a string that represents an angular value. Optionally, you can specify the unit 


atof 


distof 


atoi 


ascii 


vl-string-elt 


that defines the formatting of the number in the string. The function returns a real 
number based on the value in the string and the unit argument that is specified. You 
can use the AutoLISP angtos function to reverse the conversion. 


Accepts a string that represents a numeric value and returns a real number based on 
the value in the string. You can use the AutoLISP rtos function to reverse the 
conversion. 


Accepts a string that represents a distance value. Optionally, you can specify the unit 
that defines the formatting of the number in the string. The function returns a real 
number based on the value in the string and the unit argument that is specified. You 
can use the AutoLISP rtos function to reverse the conversion. 


Accepts a string that represents a numeric value and returns an integer based on the 
value in the string. You can use the AutoLISP itoa function to reverse the conversion. 


Accepts a string and returns an integer that represents the ASCII code value of the 
first character in the string. Although the string can be more than one character, only 
the first character is converted. You can use the AutoLISP chr function to reverse the 


conversion. 


Accepts a string and returns an integer that represents the ASCII code value of the 
character at the specified position in the string. You can use the AutoLISP chr func- 
tion to reverse the conversion. 


The following are examples of the angtof, atof, distof, atoi, ascii, and vl-string-elt func- 
tions, and the values they return: 


(angtof "90") 


1.5708 


(angtof "30.00000" 0) 


0.523599 


(atof "1.3750") 


1.375 


(distof "1 3/8\"" 4) 


1.375 


(distof "1.3750\"" 3) 


1.375 
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(atoi "-25") 

-25 

(atoi "5") 

5 

(atoi "5th Place") 
5 

(ascii " ") 

32 

(ascii "A") 

65 

(vl-string-elt "Programming" 4) 
114 


For more information on these functions, see the AutoCAD Help system. 


Converting Numeric Values to Other Number Types 
There are times when you have to work with an integer or a real number, even if a function 
returns a different numeric data type. In addition to converting integers to reals or reals to inte- 
gers, you can also convert a negative number to a positive number. 

Table 3.4 explains the functions that can be used to convert one numeric value to another. 


TABLE 3.4: AutoLISP functions for converting numeric values 


FUNCTION DESCRIPTION 


fix Accepts a numeric value, integer or real number, and returns the nearest integer after 
discarding the value after the decimal place. 


float Accepts a numeric value, integer or real number, and returns a real number. 


abs Accepts a numeric value, integer or real number, and returns the absolute value of the 
numeric value. The absolute value is a positive value, never negative. You can also multiply 
a numeric value by -1 to convert a positive to a negative numeric value or a negative to a 
positive numeric value. The AutoLISP minusp function can be used to determine whether 


a numeric value is negative. 


The following are examples of the fix, float, and abs functions, and the values they return: 


(fix -25) 
25 

(fix 25.5) 
25 

(float -25) 
-25.0 


(float 25.5) 
25,5 


RETURNING A VALUE FROM A CUSTOM FUNCTION 


(abs -25) 
25 

(abs 25.5) 
25.5 


For more information on these functions, see the AutoCAD Help system. 


Returning a Value from a Custom Function 


Almost all AutoLISP functions return some sort of value—a number, string, or even nil. In 
Chapter 2 you learned how to create custom functions, but I didn’t explain how you can specify 
a return value for a custom function. The value a custom AutoLISP function returns is always 
based on the last expression that is evaluated, which doesn’t need to be an AutoLISP expression 
in the traditional sense; it doesn’t need to contain a function and be surrounded by parentheses. 

Listing 3.3 contains a custom AutoLISP function that divides two numbers and will return 
either nil or a numeric value. nil is returned instead of the resulting quotient when a zero is 
passed as an argument value. The reason for the nil is because there is no Else statement to the 
if function and the if function is the last function to be evaluated 


LISTING 3.3: The /s function—dividing by 0 returns nil 


; Safely divides two numbers 
3 Checks to make sure that one or both of the numbers are not zero 
; (/s 0 2) 
(defun /s (numl num2 / quotient) 
(setq quotient 0) 
(if (and (not (zerop num1)) 
(not (zerop num2) ) 


) 
(setq quotient (/ numi num2) ) 


(/s © 3) 
nil 


(/s 3 0) 
nil 


(/s 2 3) 
0 


(/s 2.0 3) 
0.666667 
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Without the if function to verify that it is safe to divide the two numbers, there would be no 
point in creating the custom function, as it would be the same as the regular / (divide) function. 
However, it is valid to add a variable as the last expression in a function. The variable is then 
evaluated and its value is returned. Listing 3.4 contains a custom AutoLISP function similar to 
the one shown in Listing 3.3, but the resulting quotient is returned instead. 


LISTING 3.4: The /s function—dividing by 0 returns 0 


; Safely divides two numbers 
; Checks to make sure that one or both of the numbers are not zero 
; (/s 0 2) 
(defun /s (numl num2 / quotient) 
(setq quotient 0) 
(if (and (not (zerop num1)) 
(not (zerop num2) ) 
) 
(setq quotient (/ num1 num2) ) 
) 


quotient 


) 


(/s © 3) 
0 


(/s 3 0) 
0 


(/s 2 3) 
0 


(/s 2.0 3) 
0.666667 


Listing 3.5 demonstrates how adding an Else statement to the /s custom function would 
have also solved the problem of nil being returned when a zero is passed as an argument to the 
function. 


LISTING 3.5: The /s function—dividing by 0 returns 0 (revised) 


; Safely divides two numbers 

3; Checks to make sure that one or both of the numbers are not zero 
; (/s 0 2) 

(defun /s (numl num2 / ) 
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(if (and (not (zerop num1)) 
(not (zerop num2) ) 


) 
(/ numi num2) 
0 


) 
) 


(/s © 3) 
0 


(/s 3 0) 
0 


(/s 2 3) 
0 


(/s 2.0 3) 
0.666667 


TIP Using the AutoLISP princ function in the last statement of a custom AutoLISP function 
allows that function to “exit quietly” and not return a value. This technique is commonly used 
when a function’s name is prefixed with c:. I cover the princ function in Chapter 5. 


Exercise: Drawing a Rectangle (Revisited) 


In this section, I take another look at the drawplate function from Chapter 2, and apply some of 
the concepts that have been introduced in this chapter. The key concepts that are covered in this 
exercise are as follows: 


Using Math Functions Numeric values can be changed using basic math functions. 


Converting Values AutoLISP functions return different values, and those values can be 
converted to be used with functions that accept other types of data. 


Manipulating Strings String values can be manipulated to create a new string value. 


Storing AutoLISP Expressions You can store AutoLISP expressions in an LSP file so they 
can be used in more than one drawing or shared with others. 


Identifying the Locations of Your LSP Files AutoCAD needs to know where your LSP files 
are so it can locate them and know which locations are trusted. 


Loading LSP Files LSP files can be loaded into AutoCAD for use by the user or an 
AutoLISP program. 


You can learn more about working with LSP files in Chapter 10, “Authoring, Managing, and 
Loading AutoLISP Programs.” 
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Creating the drawplate.Isp File 
In Chapter 2, you entered the drawplate function at the AutoCAD Command prompt and 
executed the function from the current drawing. However, once you created a new drawing or 
closed the drawing that the function was typed in, it was lost unless you entered the function 
again. 

The following steps explain how to create a file named drawplate.1sp that can be used to 
store the drawplate function: 


1. Do one of the following: 


@ On Windows XP or Windows 7, click the Start button > [All] Programs > Accessories 
> Notepad. 


@ On Windows 8, on the Start Screen, type note and then click Notepad on the Search 
bar. 


2. In Notepad, click File > Save As. 


w 


In the Save As dialog box, browse to the MyCustomF7 les folder that you created under the 
Documents (or My Documents) folder, or the location in which you want to store the LSP 
file. 


In the File Name text box, type drawplate. lsp. 
Click the Save As Type drop-down list and select All Files (**). 
Click the Encoding drop-down list and select ANSI. Click Save. 


I 2 9 P 


In Notepad, click File > Save As. 
Don’t close Notepad. 


If you are running AutoCAD on Mac OS, use the following steps to create the drawplate 
. Lsp file: 


1. Inthe Mac OS Finder, click Go > Applications. In the Finder window, double-click 
TextEdit. 


2. In TextEdit, click TextEdit > Preferences. In the Preferences dialog box, on the New 
Document tab, click Plain Text and deselect Smart Quotes. Close the dialog box. 


3. Click File > New to create a plain ASCII text file. 


4. Click File > Save and type DrawPlate. lsp in the Save As text box. From the sidebar on 
the left, click Documents > MyCustomFiles, or select the location in which you want to 
store the LSP file. Click Save. 


5. If prompted to use the . lsp extension, click Use .Isp. 


6. Don't close the TextEdit window for the drawplate. lsp file. 
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Revising the drawplate Function 


In Chapter 2, you defined the drawplate function as a single function with the following 
expressions: 


(defun c:drawplate ( / old_osmode ptl pt2 pt3 pt4) 
(setq old_osmode (getvar "osmode")) 
(setvar "osmode" 0) 
(command "._-layer" "_m" "Plate" "_c" 5 "" »") 
(setq pt1 '(0 0 0)) 
(setq pt2 '(5 0 0)) 
(setq pt3 '(5 2.75 0)) 
(setq pt4 '(0 2.75 0)) 
(command "._line" ptl pt2 pt3 pt4 "_c") 
(setvar "osmode" old_osmode) 


) 


If you look at the drawplate function, it contains expressions that are used to create a layer 
and draw objects that form a rectangle. Creating or setting a layer is a common task that you 
will want to perform each time you add objects to a drawing; the same could be true about 
drawing rectangles, depending on the type of drawings you create. The following two functions 
are the result of modularizing the expressions of the drawplate function that were used to cre- 
ate a layer and draw a rectangle: 


(defun createlayer (name color / ) 
(command "._-layer" "_m" name "_c" color "" "") 


(defun createrectangle (ptl pt2 pt3 pt4 / old_osmode) 
(setq old_osmode (getvar "osmode")) 
(setvar "osmode" 0) 


(command "._line" ptl pt2 pt3 pt4 "_c") 


(setvar "osmode" old_osmode) 


) 


If you look at the createlayer and createrectangle functions, you'll see that they both 
accept values in the form of arguments that are used by the expressions that make up the func- 
tion. Arguments allow a function to be more flexible and perform the same task in different 
situations. For example, createlayer could be used to create a Door layer, which is green, 
or the Plate layer, which is blue. I discussed how to create functions that accept arguments in 
Chapter 2. 

A revised version of the drawplate function using the separate functions that create a layer 
and draw a rectangle might look like this: 


(defun c:drawplate_rev ( / ptl pt2 pt3 pt4) 
(createLayer "Plate" 5) (setq width 5 
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height (/ width 2)) 


(setq pt1 '(0 0 0) 
pt2 (list width 0 0) 
pt3 (list width height 0) 
pt4 (list © height 0)) 


(createRectangle pt1 pt2 pt3 pt4) 
) 


Along with breaking code down into smaller functions, thereby making the code modular, 
you can take the same approach to how the functions are stored. Using this approach, let’s you 
store the three functions in two files: drawplate. lsp and utility. lsp. 


@ drawplate.1sp will contain the functions that will be exposed to the user: the original and 
revised versions of the drawp Late function. 


@ utility.tsp will contain the createlayer and createrectangle functions, making it 
easier to reuse the functions with other programs if needed. 


Adding the Revised drawplate Function to drawplate.Isp 

Now that you have seen how the drawplate function can be broken down into smaller func- 
tions, it is time to add the revised function to the drawplate. lsp file and use it in AutoCAD. 
The following steps explain how to update the drawplate. lsp file: 


1. In NotePad or TextEdit, open the file drawplate. lsp. 


2. In the text editor area, position the cursor in front of the first expression of the original 
drawp late function. Hold down the Shift key and click after the last expression of the 
function. 


3. With the expressions of the function highlighted, type the following: 


; Draws a rectangular plate that is 5x2.75 
(defun c:drawplate ( / ptl pt2 pt3 pt4 width height insPt textValue) 


; Create the layer named Plate or set it current 
(createlayer "Plate" 5) 


; Define the width and height for the plate 
(setq width 5 
height 2.75) 


; Set the coordinates to draw the rectangle 

(setq pt1 '(0 © 0) ;| lower-left corner |; 
pt2 (list width 0 0) ;| lower-right corner |; 
pt3 (list width height 0) ;| 
pt4 (list 0 height 0)) Ail 


upper-right corner |; 
upper-left corner |; 
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; Draw the rectangle 
(createrectangle pt1 pt2 pt3 pt4) 


; Set the insertion point for the text label 
(setq insPt (list (/ width 2.0) (+ height 1.0) 0)) 


; Define the label to add 

(setq textValue (strcat "Plate Size: " 
(vl-string-right-trim " .0" (rtos width 2 2)) 
Wy 
(vl-string-right-trim " .0" (rtos height 2 2)) 


; Create label 
(createlayer "Label" 7) 
(createtext insPt "_c" 0.5 0.0 textValue) 


4. Click File > Save. 


Creating the utility.Isp File 


Now that you have the revised version of the drawplate function in the drawplate. lsp 

file, you need to create the utility. lsp file that will store the functions createlayer and 

createrectangle. You will also define a function named createtext. That function will be used 

to place a single-line text object below the plate that is drawn with the createrectangle function. 
Follow these steps to create the utility. lsp file, and add the createlayer, 

createrectangle, and createtext functions: 


1. Open Notepad or TextEdit, and create a file named utility. tsp. Use the steps from the 
“Creating the drawplate . lsp File” section if you need additional information. 


2. In NotePad or TextEdit, in the text editor area, type the following: 


3; CreateLayer function creates/modifies a layer and 
; expects to argument values. 
(defun createlayer (name color / ) 

(command "._-layer" "_m" name "_c" color "" "") 


; Createrectangle function draws a four-sided closed object. 
(defun createrectangle (ptl pt2 pt3 pt4 / old_osmode) 
; Store and change the value of the OSMODE system variable 
(setq old_osmode (getvar "osmode") ) 
(setvar "osmode" 0) 


; Draw a closed object with the LINE command 
(command "._line" pt1 
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pt2 
pt3 
pt4 WG") 


; Restore the value of the OSMODE system variable 
(setvar "osmode" old_osmode) 


; Createtext function creates a single-line text object. 
(defun createtext (insertionPoint alignment height rotation textString / old_ 
osmode) 

; Store and change the value of the OSMODE system variable 

(setq old_osmode (getvar "osmode") ) 

(setvar "osmode" 0) 


; Creates a single-line text object with the -TEXT command 
(command "._-text" "_j" alignment 

insertionPoint 

height 

rotation 

textString) 


; Restore the value of the OSMODE system variable 
(setvar "osmode" old_osmode) 


3. Click File > Save. 


Loading the LSP Files into AutoCAD 


Before the AutoLISP expressions in the drawplate. lsp and utility. lsp files can be used, the 
files must be loaded into AutoCAD. The Load/Unload Applications dialog box (appload com- 
mand) can be used for this purpose. 

The following steps explain how to load the LSP files into AutoCAD: 


Dg 1. Make AutoCAD the active program and do one of the following: 


@ On the ribbon, click the Manage tab > Customization panel > Load Application 
(Windows). 


@ On the menu bar, click Tools > Load Application (Mac OS). 
@ At the Command prompt, type appload and press Enter (Windows and Mac OS). 


2. When the Load/Unload Applications dialog box (see Figure 3.2) opens, browse to the 
MyCustomFi les folder and select the drawplate . lsp file. Click Load. 


FIGURE 3.2 
Loading the LSP 
files 
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3. If the File Loading - Security Concerns message box is displayed, click Load. 

4. Repeat steps 2 and 3, but select the utility. lsp file to load this time. 

5. Click Close to return to the drawing area. 

6. At the Command prompt, type drawplate press Enter. 

7. Type zoom and press Enter, and then type e to use the Extents option and press Enter. 


The rectangle that represents the plate is drawn with a single-line text object drawn above it, 
as shown in Figure 3.3. 


FIGURE 3.3 Plate Size: 5x2.75 


Results of the cus- 
tom drawplate 
function 


Chapter 4 


Working with Lists 


In the AutoLISP® programming language, an atom can be a function name, string, integer, real 
number, or another supported data type or symbol. A list is an expression that contains one or 
more atoms enclosed in parentheses. Each AutoLISP expression is a list, with the exception of 
those that start with an exclamation point. Lists often represent the following: 


+ 2D points or 3D points 


@ Entity data that defines an object and its properties, commonly referred to as an association 
list containing dotted pairs 


@ Anobject transformation matrix 
@ A grouping of related data, such as all the layers or layouts in a drawing 


In this chapter, you will learn to create and modify lists that represent coordinate values 
(points) and general data lists that contain one or more values. You will also learn to use geo- 
metric calculation functions that allow you to create new coordinate values from an existing 
coordinate values. 


What Are Lists? 


Lists are a data structure that can contain one or more elements that are placed between open- 
ing and closing parentheses. A list is comparable to an array in other programming languages. 
The elements in a list can be an AutoLISP function name or values based on one of the sup- 
ported data types that you learned about in Chapter 2, “Understanding AutoLISP.” The values 
in a list can be of the same or different data types. Although each AutoLISP expression is techni- 
cally a list, in this chapter the lists referred to are those expressions that contain any number of 
values. 

The two most common AutoLISP lists are point lists and entity data lists. A point list contains 
either two or three numeric values that represent the X and Y coordinate values along with an 
optional Z coordinate value for a point in a drawing. The following code shows a point list that 
represents the coordinate value of 2.25, 6.5, 0.0: 


(2.25 6.5 0.0) 


Another common use for lists in AutoLISP is to represent an object and its properties through 
the use of entity data lists and dotted pairs. The following code is an example of a list that creates a 
new circle at the coordinate value of 5, 6.5 with a radius of 2: 


((O ~ "CIRCLE") (10 5.0 6.5 0.0) (40 . 2.0)) 
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In Chapter 6, “Creating and Modifying Graphical Objects,” you'll learn how to create and 
work with entity data lists and dotted pairs. 

Lists can improve the way you do your job, depending on what tasks you are trying to auto- 
mate with AutoLISP. Point lists can be used with commands executed by a command function, 
and entity data lists can be used to create and modify objects without a command function. 

Although I have nothing against command functions, I learned after a few years of writ- 
ing AutoLISP programs that there was a downside to relying on such functions. As AutoCAD 
evolves and new releases are issued, commands can change in ways that cause custom pro- 
grams to no longer work correctly after you upgrade to the latest release. By relying less on stan- 
dard commands, my programs require fewer changes between releases and are more flexible. 

Creating and modifying objects directly with entity data lists can add some complexity to a 
program, but can also reduce the impact that system variables have on custom programs. For 
example, when you're using a command, running object snaps need to be disabled; when you're 
working with entity data lists, they don’t. Based on the number of objects you need to create, 
directly working with entity data can also be faster. 

Learning to work with entity data lists also allows you to create or modify objects that you 
normally can’t manipulate from the Command prompt. For example, tables can’t be created, 
populated, or modified easily (or at all) from the Command prompt. You can’t create and modify 
table styles from the Command prompt. You can do all that and more using entity data lists. 


A Real World Scenario 
LISTS TO THE RESCUE 


Ever have one of those days when you wish you hadn't opened your email? Imagine that the first 
message you read today contained the results from a drop test that showed the chassis bolts. Results 
from a drop test showed that the chassis bolts in your latest design are too small; several sheared 
off. Not only do you need to update the bill of materials (BOM) for all six models, but hole sizes 
need changing in 24 drawings. And now, corporate wants BOMs presented on each drawing—in 
alphabetical order, no less! Three headaches in less than five minutes. Thank goodness for AutoLISP. 


First, you set up a custom program. Use filter lists to create selection filters that allow you to select all 
of those circles that represent the bolt holes. You can also use filter lists to select objects on a specific 
layer or even blocks with a specific name. Once the circles are selected, changing the size is a snap. 


Now, on to the BOM. You create a BOM program that tabulates the objects and values in the draw- 
ings and places the results in a table. Lists can be created of the circles and other graphical objects, 
attribute values from the blocks, or the names of all the blocks inserted into a drawing. Once the 
list is populated, you then sort and count similar values. Finally, you place the results into each 
drawing as lines and text or a table object. 


For today, AutoLISP lists are your best friend. 


CREATINGALIST| 73 


Creating a List 


When you want to define a point list, use the List function. The following code creates a 2D 
point list that represents the point 2.25, 6.5 in a drawing: 


(list 2.25 6.5) 
(2.25 6.5) 


If you were to enter (2.25 6.5) at the AutoCAD Command prompt, the message error: bad 
function: 2.25 would be displayed. Remember that the first atom or element entered after an 
opening parenthesis must be a function. The error message is letting you know AutoLISP doesn’t 
know anything about the function named 2.25. 

The following shows the syntax of the list function: 


(list atomN) 


The atomN argument represents the values or expressions that should be combined to create a 
list. 

Here are some examples of lists created with the list function and the values that are 
returned: 


; 2D Point - Coordinate 5,2.25 
(list 5.0 2.25) 
(5.0 2.25) 


; 3D Point - Coordinate 5,2.25,1 
(list 5 2.25 1) 
(5 2.25 1) 


; Appends two lists to create a point list 
(setq Z 0.0) 

(append (list 5 2.25) (list Z)) 

(5 2.25 0.0) 


In addition to the list function, you can use the quote function to define a list. As an alter- 
native to the quote function, you can use an apostrophe ('). Although the list and quote 
functions are similar, there is one main difference between the two functions: The list func- 
tion evaluates all variables and expressions that it is passed before returning a list, whereas the 
quote function doesn’t evaluate any of the variables or nested expressions it is passed before 
returning a list. 

The following expression shows the syntax of the quote function expressed with and with- 
out the apostrophe: 


"(expressionN) 
or 
(quote expressionN) 


The expressionN argument represents the expressions that should be combined to create 
a list. 
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The following are examples of lists created with the quote (‘ ) function and the values that 
are returned: 


; 2D Point - Coordinate 5,2.25 

"(5.0 2.25) 

(5.0 2.25) 

; 3D Point - Coordinate 5,2.25,1 

(quote (5 2.25 1)) 

(5 2.25 1) 

; Appends two lists without evaluating the variables 
(append '(5 2.25) (quote (Z))) 

(5 2.25 Z) 


In addition to the AutoLISP list and quote (’) functions, you can use the cons and vl-list* 
functions. I discuss how to use the cons function in Chapter 6. The vl-list* function combines 
the functionality of the List and cons functions; see the AutoCAD Help system for more infor- 
mation on the vl-list* function. 

This exercise shows how to create two point lists that represent the opposite corners of a 
desk’s top: 


1. 


At the AutoCAD Command prompt, type (setq width 60 depth 30) and press Enter. 


The user-defined variables width and depth are assigned the values 60 and 30, 
respectively. 


Type (setq LL '(0 © 0)) and press Enter. 


(9 © 0) is assigned to the LL user-defined variable. The apostrophe before (0 © 0) 
results in the list not being evaluated, which is fine in this case because the list is made 
up of all static numeric values. 


Type (setq UR '(width depth ©)) and press Enter. 


(WIDTH DEPTH 0) is assigned to the UR user-defined variable. The value of (WIDTH 
DEPTH 0) is as expected because the apostrophe tells AutoLISP not to evaluate the val- 
ues before returning the list. Remember, when using variables in a list you usually want 
them to be evaluated so that the values that are assigned are used. 


Type (setq UR (list width depth 0)) and press Enter. 


(60 30 0) is assigned to the UR user-defined variable. Since the list function does evalu- 
ate the variables in a list, a value point list is assigned to the UR user-defined variable. 


Type (command "._line"™ LL UR "" "._zoom" "_e") and press Enter. 


The Line command draws a line between the points specified by the LL and UR user- 
defined variables. The zoom command with the e option zooms to the extents of the 
objects in the drawing. 


Getting an Element from a List 


A value ina list is known as an element. You can retrieve a specific element from a list by refer- 
encing the element's index, or step through a list and perform an action on each element. The 
first element of a list is not located at 1 as you might think, but rather at 0. The second element 
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is at index 1, and so on. For example, in a 2D point list (X Y), the X coordinate value is located at 
index 0, whereas the Y coordinate value is located at index 1. 


Retrieving a Specific Element 
You can retrieve a specific element from a list based on a known index or get the position of an 
element within a list based on the element’s value. Getting a specific element in a list allows you 
to pass that value to an AutoLISP function or add the value to a new list. For example, a new 
point list can be created from the elements in one or more point lists. 

The AutoLISP car function can be used to return the first element of a list, whereas its com- 
panion function, cdr, returns a new list with the first element removed. The following shows 
the syntax of the car and cdr functions: 


(car list) 
(cdr list) 


The list argument represents the list from which you want to retrieve a value. 
The following are examples of the car and cdr functions, and the values that are returned: 


; 3D Point list - Coordinate 5,2.25,1 
(setq pt '(5.0 2.25 1)) 

(5 2.25 1) 

; Return the X coordinate value 

(car pt) 

5 

; Return the Y and Z coordinate values 
(cdr pt) 

(2.25 1) 


Although the car function can be used to get the first element of a list, you can use the car 
and cdr functions in a nested AutoLISP expression to get other elements from a list. The follow- 
ing shows how to get the second and third elements (Y and Z coordinate values) of a point list: 


; Return the Y coordinate value 
(car (cdr pt)) 

2025 

; Return the Z coordinate value 
(car (cdr (cdr pt))) 

I 


Using multiple car and cdr functions to retrieve elements from large lists can become over- 
whelming. To make it easier to access specific elements within a list, AutoLISP provides a num- 
ber of functions that combine the functionality of the car and cdr functions. For example, you 
can use the functions cadr and caddr to retrieve the first and second elements of a list. The fol- 
lowing shows how to get the first and second elements (Y and Z coordinate values) of a point list: 


; Return the Y coordinate value 
(cadr pt) 

2:25) 

; Return the Z coordinate value 
(caddr pt) 

L 
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NOTE AutoLISP supports combinations of the car and cdr functions up to four levels. These 
functions start with the letter € and end with r. Between the ¢ and r, you add an a when you 
want to use the car function and d when you want to use the cdr function. The combination 
functions are read from right to left. For example, the caddr function performs a cdr on the 
list passed to the function first, a second cdr is performed on the listed returned, and then 
that is followed by a car function. For a full listing of the supported combinations, search on 
the keywords “point lists” in the AutoCAD Help system. 


This exercise shows how to create two point lists based on the current values assigned to 
other point lists: 


1. At the AutoCAD Command prompt, type (setq UR (list 60 30)) and press Enter. 
2. Type !UR and press Enter. 
(60 30), which is the value assigned to the UR user-defined variable, is returned. 
3. Type (car UR) and press Enter. 
60 is returned because the car function returns the first element of a list. 
4. Type (cadr UR) and press Enter. 
30 is returned because the cadr function returns the second element of a list. 
5. Type (setq LL (list © 0)) and press Enter. 
(0 ©) is assigned to the LL user-defined variable. 
6. Type (setq UL (list (car LL) (cadr UR))) and press Enter. 


(9 30) is assigned to the UL user-defined variable. The new list is created by the first ele- 
ment of the list assigned to the LL user-defined variable and the second element of the list 
assigned to the UR user-defined variable. 


7. Type (setq LR (list (car UR) (cadr LL))) and press Enter. 


(60 0) is assigned to the LR user-defined variable. The new list is created by the first ele- 
ment of the list assigned to the UR user-defined variable and the second element of the list 
assigned to the LL user-defined variable. 


8. Type (command "._pline™ LL LR UR UL "_c" "._zoom" "_e") and press Enter. 


The pline command draws a four-segment polyline that forms a rectangle. The zoom 
command with the e option zooms to the extents of the objects in the drawing. 


Instead of using just the car, cdr, or a combination of the two functions to retrieve an ele- 
ment from a large list, you can use the AutoLISP nth function. The nth function returns an 
element from a list based on a specific index value, starting with 0. If an element exists at 
the specified index, the value of the element is returned; otherwise, if the list doesn’t contain 
enough elements based on the index value passed to the nth function, the function returns nil. 

The following shows the syntax of the nth function: 


(nth index list) 


Here are the arguments: 


GETTING AN ELEMENT FROM A LIST 


index The index argument represents the position in the list for the element you want to 
retrieve; 0 is the first element in a list. 


list The list argument represents the list from which you want to retrieve a value. 


The following are examples of the nth function and the values that are returned: 


; 3D Point - Coordinate 5.0,2.25,1 
(setq pt '(5.0 2.25 1)) 

(5.0 2.25 1) 

; Return the X coordinate value 
(nth 0 pt) 

5.0 

; Return the Y coordinate value 
(nth 1 pt) 

2.25 

; Return the Z coordinate value 
(nth 2 pt) 

I 


In addition to the AutoLISP car, cdr, and nth functions, you can use the last function to get 
the last element of a list or the vl-position function to get the index of a specific value within a 
list. The following examples demonstrate the use of the last and vl-position functions: 


; Create a list with system variable names 
(setq vars '("osmode" "cmedecho" "filedia")) 
("osmode" "cmedecho" "filedia") 
; Return the last element of the list 
(last vars) 
"filedia" 
; Return the index of the value in the list 
(vl-position "cmdecho" vars) 
li 
(vl-position "cmddia" vars) 
nil 
For more information on the Last and vl-position functions, see the AutoCAD Help 
system. 
This exercise has you working with a list containing several string values that represent the 
seven standard AutoCAD colors. You will use the nth function to retrieve a specific element 


from the list and get the last element in the list with the Last function: 


1. At the AutoCAD Command prompt, type (setq namedColors (list "Yellow" "Red" 
"Green" "Cyan" "Blue" "Magenta" "White")) and press Enter. 


2. Type (nth © namedColors) and press Enter. 


"Yellow" is returned because it is in the first position of the list, which as I previously 
mentioned is at index 0. 


3. Type (nth 4 namedColors) and press Enter. 


"Blue" is returned because it is the fifth element in the list or the element at index 4. 
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4. Type (nth 7 namedColors) and press Enter. 
nil is returned because it is outside the length of the list. 
5. Type (last namedColors) and press Enter. 


"White" is returned since it is the last element in the list. 


Stepping Through a List 
Lists commonly don’t have a fixed number of elements like a point list, which has either two 
or three elements. When you're working with graphical and nongraphical objects, the data list 
for an object might have fewer than 10 elements for one object, whereas it could have dozens of 
elements for another object. Getting each element of a point list with the car, cdr, or nth func- 
tions is fairly straightforward since you have to work with only two or three elements. Instead of 
getting each element with its own expression, you can use a looping expression to step through 
the list one element at a time. As you step through a list, you can use an element in an expres- 
sion and then proceed to the next element in the list until you have accessed all of the elements 
in the list. 

The AutoLISP foreach function is designed specifically for stepping through the elements of 
a list. There are other functions that could be used to step through a list or even execute a series 
of AutoLISP expressions until a condition is met. I cover other functions that can be used to cre- 
ate looping expressions in Chapter 5, “Requesting Input and Using Conditional and Looping 
Expressions.” 

The following is the syntax of the foreach function: 


(foreach variable list [expressionN ...]) 
Here are the arguments: 


variable The variable argument represents the user-defined variable that each element of 
the list argument will be assigned as the list is processed. 


list The list argument represents the list that you want to step through. 


expressionN The expressionN argument represents the expressions that should be exe- 
cuted for each element in the list argument. The value of the list element is accessed with the 
name in the variable argument. 


The following is an example of the foreach function, which steps through a list that contains 
the name of each named layout in a drawing: 


; List of standard AutoCAD colors 
(setq namedColors (list "Yellow" "Red" "Green" "Cyan" "Blue" "Magenta" "White"’) ) 
Returns: ("Yellow" "Red" "Green" "Cyan" "Blue" "Magenta" "White") 
; Step through and output the name of each element in the list 
(prompt "\nColors: ") 
(foreach color namedColors 

(prompt (strcat "\n " color)) 
) 
Returns: 
Colors: 

Yellow 
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Red 
Green 
Cyan 
Blue 
Magenta 
White 
nil 
The previous example uses the AutoLISP prompt function, which is used to display a string 
in the command-line window. I will discuss this and other functions that can be used to provide 
feedback to the user in Chapter 5. 
Knowing the number of items in a list can be helpful when you want to step through a list 
using the AutoLISP while or repeat function, described in Chapter 5. The following shows the 
syntax of the length function: 


(length list) 


The list argument represents the list for which you want to know the number of elements. 
The following are examples of the length function and the values that are returned: 


(setq namedColors (list "Yellow" "Red" "Green" "Cyan" 

"Blue" "Magenta" "Wwhite")) 
("Yellow" "Red" "Green" "Cyan" "Blue" "Magenta" "White") 
(length namedColors) 


7 
(length '(0 3 0)) 
3 

(length '()) 

0 


TIP Youcanalso use the AutoLISP vl-list- length function to return the number of elements 
in alist. However, unlike the Length function, the vl- List- length function doesn’t produce 
an error if a list represents a dotted pair. You'll learn about dotted pairs in Chapter 6. 


Appending, Substituting, and Removing Elements 


The AutoLISP list and quote functions allow you to create a list based on a set of known 
values. However, there will be times when you want to create a list based on a set of unknown 
values. For example, you might want to create a list of objects that your program created in a 
drawing while the drawing remains open, or a list of the system variables that you have recently 
changed so they can be restored. 


Appending Elements 


You can append an atom to an existing list using the AutoLISP append function. You must 
ensure that the atom is contained in a list before you pass it to the append function. After the 
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lists are appended together, a new list is returned with the elements of all the lists passed to the 
append function. 
The following shows the syntax of the append function: 


(append [listN ...]) 


The listN argument represents the lists that you want to append together. nil can be passed 
as a list for the listN argument. The order in which lists are passed to the append function is the 
same order in which they are appended. The listN argument is optional. If no list is passed to 
the listN argument, the append function returns nil. 

The following are examples of the append function and the values that are returned: 


(append) 

nil 

(append '("X") '("y" "z")) 
("x" "y" o"z") 

(append nil '("1" "2")) 
Caen) 

(setq Z 5) 

(append (list © 0) (list Z)) 
(0 0 5) 


Much of the time you will likely be working at the current elevation, so you will only need 
to work with points that need an X and Y coordinate value. However, you might need to place 
objects at different elevations; this requires you to supply a Z coordinate value as part of the 
point list. This exercise shows how to add a Z coordinate value to a 2D point list: 


1. 


At the AutoCAD Command prompt, type (setq LL '(@ 0) UR '(60 30)) and press 
Enter. 


Type (command "._rectang" LL UR) and press Enter. 


The rectang command draws a four-sided rectangle on the current working plane. 


3. Type (setq Z '(5)) and press Enter. 


4. Type (setq LL (append LL Z)) and press Enter. 


(0 © 5) is returned. The append function returns the results of combining the two lists, 
(0 ©) and (5), together. 


Type (setq UR (append UR Z)) and press Enter. 
(60 30 5) is returned. 


Type (command "._rectang" LL UR "._-view" "_swiso" "._zoom" "_e") and press 
Enter. 


The rectang command draws a rectangle at an elevation of five units above the current 
working place. The -view command with the swiso option sets the southwest isometric 
view as current, whereas the zoom command with the e option zooms to the extents of 
the objects in the drawing. 
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Substituting Elements 


An element in a list can be replaced with a new element or list. Substituting an element for 
another can be done with the AutoLISP subst (short for substitution) function. The subst func- 
tion returns either a new list containing the updated element or nil. A new list is returned only 
when the old element is successfully found and the substitution occurs. 

The following shows the syntax of the append function: 


(subst new_element old_element list) 
Here are the arguments: 


new_element The new_element argument represents the element that should be used to 
replace the element specified by the old_element argument if found in the list argument. 


old_element The old_element argument represents the element that is to be replaced if 
found in the list argument by the element specified with the new_element argument. 


list The list argument represents the list that contains the element you want to replace. 


The following are examples of the subst function and the values that are returned: 


(subst Way" "A?" "maz" "B1" "C1")) 

("AL" "B1" "C1") 

(subst Way" "A!" '("A?" "B1" "C1")) 

("A2" "B1" "C1") 

(subst '(1 2 0) '(0 0 ©) '((0 © 0) (5 5 0))) 
((1 2 0) (5 5 0)) 


The AutoLISP subst function is very useful when you're creating and modifying entity data 
lists that represent the properties of an object. You'll learn how to create and modify the values 
of an entity data list with the subst function in Chapter 6. 


Removing Elements 


Elements located in a list can be removed when they are no longer needed. Earlier you saw how 
the AutoLISP cdr function can be used to remove the first element from a list, but often you will 
want to remove an element based on its current value. You can also step through a list using the 
foreach function, and then evaluate the value of each element in the list and determine which 
elements should be removed. An element can be more efficiently removed using the AutoLISP 
vl-remove function. 

The following shows the syntax of the vl- remove function: 


(vl-remove element list) 


Here are the arguments: 


element The element argument represents the element that should be removed from the list 
specified by the list argument. If more than one element in the list is matched, all matched 
elements are removed. 


list The list argument represents the list that contains the element you want to remove. 


The following are examples of the vl- remove function and the values that are returned: 
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(vl-remove WA?" '("A?" wei" "C1")) 

("B1" "C1") 

(setq lst (list "A1" "B1" "A1" "C1")) 

(vl-remove (nth 3 lst) lst) 

("A1" "BL" "A1") 

(setq lst (list "A1" "B1" "A1" "C1")) 

(vl-remove (nth 2 lst) lst) 

("BLY "C1") 

(vl-remove '(0 0 0) '((0 © 0) (1 2 0) (2 4 0) (5 5 0))) 
((1 2 0) (2 4 0) (5 5 0)) 


In addition to removing an element by its value, you can remove from a list all elements that 
don’t match a test function. The test function that is used must return T or nil. For example, you 
could remove all the numbers from or keep all the numbers in a list. The AutoLISP functions 
that allow you to filter elements by their value from a list are as follows: 


vl-remove-if Removes from a list all elements that result in the test function returning T 


vl-remove-if-not Removes from a list all elements that result in the test function 
returning nil 


The following are examples of the vl-remove-if and vl-remove-if-not functions, and the 
values that are returned: 


(vl-remove-if 'numberp '("A2" 1 1.5 T PI (0 © 0))) 
("A2" T PI (0 0 0)) 

(vl-remove-if-not 'numberp '("A?" 1 1.5 T PI (0 © 0))) 
(1 1.5) 


For more information on the AutoLISP vl-remove-if and vl-remove-if-not functions, see 
the AutoCAD Help system. 


Determining Whether an Item Exists in a List 


When creating and modifying a list, you might want to search the list for the existence of an 
element with a specific value before trying to add or remove an element that would contain the 
same value. Although you could step through a list to determine whether an element with a 
specific value already exists, the AutoLISP member function is a more efficient way to search for 
a value ina list. The member function returns a list containing the element that matches the test 
expression along with all the elements after it; otherwise nil is returned. 

The following is the syntax of the member function: 


(member expression list) 
Here are the arguments: 


expression The expression argument represents the element that you want to search for in 
the list specified by the list argument. 


list The list argument represents the list that contains the element you want to search for. 
The following are examples of the member function and the values that are returned: 


(member "B1" '("A?" "B1" "C1")) 
("B1" WET") 
(member "D1" '("A?" "B1" "C1")) 
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nil 
(member '(2 4 0) '((0 © 0) (1 2 0) (2 4 0) (5 5 0))) 
((2 4 0) (5 5 0)) 


You can also search all elements in a list and return the element that matches the result of a 
test function in addition to all elements after it. The test function that is used must return T or 
nil. For example, you could search for a number or non-numeric value in a list, and return the 
first element that matches the test condition and all the elements after it in the list. The AutoLISP 
functions that allow you to search for elements in a list are as follows: 


vl-member-if Searches the elements ina list and returns the first element that causes the test 
function to return T. All elements after the first element that results in a match are also 
returned. 


vl-member-if-not Searches the elements in a list and returns the first element that causes 
the test function to return nil. All elements after the first element that results in a failed match 
are also returned. 


The following are examples of the vl-member -if and vl-member-if-not functions, and the 
values that are returned: 


(vl-member-if 'numberp '("A2" 1 1.5 T PI (0 © 0))) 

(1 1.5 T PI (0 © @)) 

(vl-member-if-not 'numberp '("A?" 1 1.5 T PI (0 © 0))) 
("A2" 1 1.5 T PI (0 © 0)) 


Although the vl-member-if and vl-member-7f-not functions can be used to search for the 
first element that does or doesn’t match the test function, you can also check to see if one or all 
of the elements in a list match a test function. The AutoLISP functions that allow you to test the 
elements in a list are as follows: 


vl-some Tests to see if one or more elements in a list causes the test function to return T. If at 
least one element causes the test function to return T, the v_-some function returns T; other- 
wise, ni lis returned. 


vl-every Tests to see if all elements in a list cause the test function to return T. If all elements 
cause the test function to return T, the v l-element function returns T; otherwise, ni Lis 
returned. 


The following are examples of the vl-some and vl-every functions, and the values that are 
returned: 


(vl-some 'numberp '("A?" 1 1.5 T PI (0 © 0))) 


T 
(vl-some 'numberp '("A?" "B1" "C1")) 

nil 

(vl-every 'numberp '("A?" 1 1.5 T PI (0 © 0))) 
nil 


For more information on the AutoLISP vl-member-if, vl-member-if-not, vl-some, and vl- 
every functions, see the AutoCAD Help system. 
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Sorting the Elements of a List 


Elements in a list often don’t need to be in any specific order except when the list represents a 
coordinate or the list will be used to present information to the user. Lists can be stored alpha- 
betically or numerically. It is even possible to sort nested values within a list. 


Table 4.1 provides an overview of the functions that can be used to sort a list. 


TABLE 4.1: AutoLISP list sorting functions 
FUNCTION DESCRIPTION 
acad_strlsort Accepts a list and sorts the elements in the list alphabetically. If the 


elements could be sorted, a new list is returned; otherwise the func- 
tion returns nil. 


vl-sort Accepts a list and sorts the elements in the list based on the results of 
a comparison function. A new list of the sorted elements is returned. 


vl-sort-i Accepts a list and sorts the elements in the list based on the results of 
a comparison function. A new list containing the indexes of the 
sorted elements is returned. 


The following are examples of the acad_strlsort, vl-sort, and vl-sort-7 functions, and 
the values they return: 


(acad_strlsort '("BC" "A2" "A1" "BB" "B1")) 
("A1" "A2" "B1" "BB" "BC") 

(vl-sort '("BC" "A2" Way" "BB" "B1") 1>) 
("BC" "BB" "B1" "A2" "A1") 

(vl-sort-i '("BC" "A2" Way" "BB" "B1") 1>) 
(0 341 2) 


For more information on the AutoLISP acad_strlsort, vl-sort, and vl-sort-i functions, 
see the AutoCAD Help system. 


TIP The acad_ strlsort function sorts all elements of a list in an ascending or alphabetic 
order. You can reverse the order of a list using the AutoLISP reverse function, which returns 
a new list of the items presented in the opposite order. If the list was previously sorted, this 
would give you a list that is now sorted in descending order. 


Using Point Lists to Calculate Geometric Values 


The math functions discussed in Chapter 3, “Calculating and Working with Values,” are great 
for calculating numeric values based on other numeric values, but they aren’t specifically 
designed to work with point lists. Although you can use the functions described in the previous 
section to get the values of a point list and then manipulate the values with the math functions, 
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AutoLISP does provide a set of functions that are designed specifically for working with point 
lists and other geometric values. AutoLISP contains functions that allow you to 


Calculate an angular or distance value between two points 


+ 


Return a new coordinate based on a starting point, in a specified direction, and along a 
specified angle 


Calculate the intersection between two lines 
Return a coordinate value at a point using an object snap 
Translate a coordinate value from one user coordinate system (UCS) to another 


Convert values between measurement units 


© ©% ¢ O@ 6% 


Access the AutoCAD calculator 


Measuring Angular and Distance Values 
When you draw or modify an object, you commonly need to know either where that object 
should be created or its geospatial relationship to other objects in a drawing. Almost all objects 
created in a drawing require you to calculate angular or distance values, if not both, so you can 
properly locate the object. You can use the AutoLISP angle and distance functions to calculate 
an angle or 3D distance between two points. The angle function returns a 2D angle in radians 
between two points as a real number, and the distance function returns a 3D distance as a real 
number between the two points. 

The following shows the syntax of the angle and distance functions: 


(angle pointi point2) 
(distance pointi point2) 


Here are the arguments: 


point1 The pointi argument represents the first coordinate. 


point2 The point2 argument represents the second coordinate on which the angular or 
distance value should be calculated. The angular value is calculated in only two dimensions; 
the Z coordinate value is ignored for the angle function. 


The following are examples of the angle and distance functions, and the values that are 
returned: 


(angle '(0 © 0) '(0 4 4)) 


1.5708 

(angle '(0 © 0) '(0 4 0)) 
1.5708 

(distance '(0 0 0) '(0 4 4)) 
5.65685 


(distance '(0 0 0) '(0 4 0)) 
4.0 
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Calculating Points 


When you create or modify an object, you frequently need to calculate a point based on another 
point on or near an object to accurately place the new object or modify the existing graphical 
object. While you could prompt the user to specify all the points you might need in the draw- 
ing, that can lead to unnecessary steps in a workflow. It is always best to calculate any and all 
points that you can with minimal input from the user. 

The AutoLISP polar function returns a 2D or 3D point in the current UCS, based on an angle 
and distance from a point. The result of a polar function is similar to specifying a relative polar 
coordinate through the AutoCAD user interface. 

The following is the syntax of the polar function: 


(polar point angle distance) 


Here are the arguments: 


point The point argument represents the coordinate point in the drawing that you want to 
calculate the new point from. If a 2D point is specified, a 2D point is returned; specifying a 3D 
point results in a 3D point being returned. 


angle The angle argument represents the angle in radians that the new point should be 
located from the coordinate point specified with the point argument. 


distance The distance argument represents the distance at which the new point should be 
calculated from the point argument and along the angle specified by the angle argument. 


The following are examples of the polar function and the values that are returned: 


(polar '(0 © 0) (/ PI 4) 3) 
(2.12132 2.12132 0.0) 
(polar '(1 2) PI 1) 

(0.0 2.0) 


Finding and Snapping to Points 

The AutoLISP polar function allows you to calculate a new coordinate point in the current UCS 
based on an angle and distance from a point. However, you will often want to work with exist- 
ing points in a drawing as well. Since objects drawn in a drawing should be accurately placed, 
you should use object snaps to make sure a point is located on an object. 

The AutoLISP osnap function allows you to acquire a point on an object using an Object Snap 
mode. The point must be within the aperture of the crosshairs. The aperture is the box at the 
intersection of the crosshairs, and the size of the aperture can be adjusted with the aperture 
system variable. If a point on an object can’t be acquired with a specified Object Snap mode, 
nilis returned; otherwise the acquired point is returned. The Object Snap modes available are 
the same that you can enter at the Command prompt when you're prompted for a point; see the 
osnap command topic in the AutoCAD Help system for a full list of Object Snap modes. 

The following shows the syntax of the osnap function: 


(osnap point osnap_mode) 
Here are the arguments: 


point The point argument represents the coordinate near an object that you want use to 
acquire a point on an object with the Object Snap mode set by the osnap_mode argument. 
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osnap_mode The osnap_mode argument represents the Object Snap modes you want to use. 
Object Snap modes are passed as a comma-delimited string. 


The following are examples of the osnap function and the values that are returned: 


; Draw a line and circle 

(command "._line™ '(0 © 0) '(2.5 4 0) "") 

(command "._ circle" '(1.25 2 0) 2) 

; Check for intersection point of the line and circle 

(osnap '(0.188 0.302 0) "_INT") 

(0.190002 0.304003 0.0) 

3; Check for center point 

(osnap '(1 1.6 0) "_CEN") 

nil 

3 Check for endpoint and midpoint, and return the object snap point found 
(osnap '(0 © 0) "_END,_MID") 

(0.0 0.0 0.0) 

3 Check for endpoint and midpoint, and return the object snap point found 
(osnap '(1 1.6 0) "_END,_MID") 

(1.25 2.0 0.0) 


The INTersection Object Snap mode with the osnap function can be used to check for the 
intersection of two or more objects, but the geometry must exist in the drawing first. The 
AutoLISP inters function allows you to calculate the intersection between two lines or vectors 
without actually creating the objects in the drawing first. If the lines or vectors don’t intersect, 
nilis returned; otherwise the intersection point is returned. The following shows the syntax for 
the inters function: 


(inters pointi point2 point3 point4 [on_segments]) 
Here are the arguments: 


point1 The pointi argument represents the first coordinate of the first line segment. 
point2 The point2 argument represents the second coordinate of the first line segment. 
point3 The point3 argument represents the first coordinate of the second line segment. 
point4 The point4argument represents the second coordinate of the second line segment. 


on_segments The on_segements argument indicates if the intersecting point must lie on the 
line segments or off the line segments by projecting the lines to infinity in both directions. The 
on_segments argument is optional, but it is enabled by default. Providing a value of nil 
indicates that vectors should be drawn to infinite lengths. 


The following are examples of the inters function and the values that are returned: 


(inters '(0 0 0) '(44 0) '(1 2 0) '(2 © 0)) 
(1.33333 1.33333 0.0) 

(inters '(2 3 0) '(0 3 0) '(1 0 0) '(1 1 0)) 

nil 

(inters '(2 3 0) '(0 3 0) '(1 © ©) '(1 1 0) nil) 
(1.0 3.0 0.0) 
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Translating Points 


A drawing contains several different coordinate systems, and it is possible to draw objects using 
coordinate systems other than the current one. Commands used with the command function 
work only in the current coordinate system, but when working with existing objects you might 
need to translate a point between two different coordinate systems. 

You can use the AutoLISP trans function to translate a coordinate value between the world 
coordinate system (WCS), current UCS, or display coordinate system. The following shows the 
syntax of the trans function: 


(trans point current_coordsystem new_coordsystem displacement) 
Here are the arguments: 


point The point argument represents the 2D or 3D point that you want to translate. 


current_coordsystem The current_coordsystem argument represents the coordinate sys- 
tem of the point argument being translated. 


new_coordsystem The new_coordsystem argument represents the coordinate system that 
the point argument is being translated to. 


displacement The displacement argument indicates if the point argument should be 
treated as a 3D displacement instead of a 3D point. The displacement argument is optional. 
Providing a value of T indicates that the point argument should be converted as a 3D displace- 
ment value. 


The following are examples of the trans function and the values that are returned: 


; Change the current UCS by rotating the X axis 
(command "._ucs" "_x" -90) 

nil 

; Convert the point from WCS to the current UCS 
(trans '(1 2 0) 0 1) 

(1.0 -4.44089e-016 2.0) 

(trans '(1.0 -4.44089e-016 2.0) 1 0) 

(1.0 2.0 -2.0985e-022) 

; Change the current UCS back to the WCS 
(command "._ucs" "_w") 

nil 


For more information on the AutoLISP trans function, search on the keywords “trans 
AutoLISP” in the AutoCAD Help system. 


Converting Measurement Units 


AutoCAD is used by many large and small companies around the world. Although it would be 
nice if there were a universal system of measurements, the fact is that there are still countries 
that use the imperial system of weights and measurements, whereas most of the world uses the 
metric system. AutoLISP can’t resolve the measurement-unit problem in the world, but it can 
help you convert from one unit of measurement to another. 

The AutoLISP cvunit function allows you to convert values between different linear, angu- 
lar, weight, volume, and other unit types. The unit types that are available for use are listed in 
the acad.unt file, which can be found in the support file search paths of AutoCAD. 


USING POINT LISTS TO CALCULATE GEOMETRIC VALUES 


The following explains the syntax of the cvunit function: 
(cvunit value current_unit new_unit) 


Here are the arguments: 


value The value argument represents the numeric or coordinate (2D or 3D) point that you 
want to convert. 


current_unit The current_unit argument represents the unit type of the value argument 
being converted. 


new_unit The new_unit argument represents the unit type that the value argument is being 
converted to. 


The following are examples of the cvunit function and the values that are returned: 


(cvunit 3.75 "m" "ft") 
12,3031 

(cvunit 15.0 "inch" "ft") 
1:25 

(cvunit '(1.0 2.0) "m" "ft") 
(3.28084 6.56168) 


Accessing the AutoCAD Calculator 

AutoCAD contains two built-in calculators that can be used to perform math and geometric cal- 
culations: the AutoCAD quickcalc command (on Windows only) and the AutoCAD cal com- 
mand. The AutoCAD quickcalc command displays either a palette or dialog box, which is less 
than ideal for AutoLISP programs because the choices a user might make are hard to predict 
and can produce unexpected results. 

The AutoCAD cal command is available from the Command prompt or as an AutoLISP 
function with the same name. The AutoLISP cal function can be very useful if your programs 
need to perform complex math and geometric calculations. The functions that are available 
to the cal function are the same as those available to the cal command. For information on 
the functions available to the cal command, search on the keywords “cal command” in the 
AutoCAD Help system. 


NOTE The geomcal.arx or geomcal.crx file must be loaded into AutoCAD before the 
AutoLISP cal function can be used. You can use the AutoLISP arxload function to load one 
of the geomcal files from the LSP file that uses the cal function. For example, (arxload 
"seomcal") will load the geomcal.arx or goamcal.crx file based on which one is found in 
the support file search paths for AutoCAD. 


The following explains the syntax of the cal function: 
(cal expression) 


The expression argument represents the string that contains the values and functions that 
should be executed by the cal function. 
The following are examples of the cal function, and the values that are returned: 


(cal "1 + 2") 
3 
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; Calculates the midpoint between two user-specified 

; points using the endpoint object snap 

(cal "(END+END) /2") 

Specify two endpoints on objects in the drawing area; the returned point list will be 
different than the following 

(8.2857 13.7603 0.0) 

; Calculates the midpoint between the coordinates 0,0,0 and 3,3,0 

(cal "([0,0,0]+[3,3,0])/2") 

(1.5 1.5 0.0) 


Converting Lists to Strings and Strings to Lists 


Lists are commonly used for coordinates, but they can also be used to represent the data that 
makes up an object or the characters that make up a string. A list of ASCII codes can be used to 
create a string, or a string can be converted into a list of ASCII codes. An ASCII code is an inte- 
ger value equivalent to a character in a string. You saw how to work with and convert strings in 
Chapter 3. 

The following explains the functions that can be used to convert a list to a string or string to 
a list: 


vl-string->list The vl-string->list function accepts a string and returns a list that 
contains the ASCII codes for all characters in the string. 


vl-list->string The vl-list->string function accepts a list of integer values that 
represent ASCII codes and returns a string based on the ASCII codes in the list. 


The following are examples of the vl-string->list and vl-list->string functions, and 
the values that are returned: 


(vl-string->list "Project address") 

(80 114 111 106 101 99 116 32 97 100 100 114 101 115 115) 

(vl-list->string '(80 114 111 106 101 99 116 32 97 100 100 114 101 115 115)) 
"Project address" 


For more information on these functions, see the AutoCAD Help system. 


Exercise: Adding Holes to the Plate 


In this section, I expand on the drawplate and utility functions that were introduced in 
Chapter 3. I also apply some of the concepts that were introduced in this chapter. The key 
concepts that are covered in this exercise are as follows: 


Calculating Numeric Values Basic math functions can be used to calculate new distances or 
increase an angle. 


Calculating New Coordinates Coordinate values can be calculated using the AutoLISP 
polar function. 


Creating and Manipulating Lists Lists can be used to store multiple values in a variable. A 
list can be created using the AutoLISP list, quote, or cons function, and elements within a list 
can be retrieved using the nth function. The append function can be used to add a new element 
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to a list, whereas the assoc function can be used to verify whether an element already exists in 
a list. If an element is ina list, the subst function can be used to replace one element with 
another. 


Stepping Through a List Each elementin a list can be retrieved and processed using the 
AutoLISP foreach function. 


NOTE Thestepsin this exercise depend on the completion of the steps in the “Exercise: Drawing 
a Rectangle (Revisited)” section of Chapter 3. If you didn’t complete the steps, do so now or start 
with the ch04_drawplate. lsp and ch04_utility.lsp sample files available for download 
from www. sybex.com/go/autocadcustomi zation. You should place these sample files in the 
MyCustomF7 les folder under the Documents (or My Documents) folder, or the location you 
are using to store the LSP files. Also, remove the “ch04_” from the name of each file. 


Defining the New Get-Sysvars and Set-Sysvars Utility Functions 

When using AutoLISP, you should always consider your end user and be mindful of the current 
AutoCAD environment. This is why I have you store the current value of a system variable in a 
local variable before you change the system variable’s value. Then, before a function ends, you 
restore the previous value of each system variable that you changed. 

To take this approach, you have to write three expressions each time you want to store, set, 
and restore the value of a system variable. You can use expressions that look similar to the fol- 
lowing code to store, set, and restore the osmode and cmdecho system variables in a custom 
function: 


(defun <function_name> (/ old_osmode old_cmdecho) 
; Store and change the value of the OSMODE and CMDECHO system variables 
(setq old_osmode (getvar "osmode") 
old_cmdecho (getvar "cmdecho") ) 


(setvar "osmode" 0) 
(setvar "cmdecho" 0) 


; Restore the value of the OSMODE and CMDECHO system variables 
(setvar "osmode" old_osmode) 
(setvar "cmdecho" old_cmdecho) 


) 


You should never feel that storing and restoring the values of the system variables is not 
worth the effort; it improves the experience that users have with your custom programs and 
AutoCAD. However, it is a bit of extra work for you as a programmer; especially if you are 
changing three or more system variables. 

As a programmer, I am almost always looking for easier and more efficient ways to write 
code. As an alternative to writing multiple expressions to store, set, and restore each system 
variable in a function, you can create custom functions that wrap and simplify the functionality 
for you. 
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The following exercise shows how to define two custom functions that allow you to store and 
then set the values of system variables that are part of a list. The functions you will be defining 
are named Get-Sysvars and Set-Sysvars. 


1. Open the utility. lsp file in Notepad on Windows or TextEdit on Mac OS. 


2. In the text editor area, position the cursor after the last expression in the file and press 
Enter twice. Then type the following; the comments are here for your information and 
don’t need to be typed: 


Get-Sysvars function returns a list of the current values 
of the list of system variables it is passed. 


; Arguments: 
sysvar-list - A list of system variables 


; Usage: (get-sysvars (list "clayer" "osmode") ) 
(defun get-sysvars (sysvar-list / values-list) 


; Creates a new list based on the values of the 
; system variables in sysvar-list 

(foreach sysvar sysvar-list 

; Get the value of the system variable and add it to the list 


(setq values-list (append values-list (list (getvar sysvar)))) 


; List to return 
values-list 


Set-Sysvars function sets the system variables in the 
sysvar-list to the values in values-list. 


; Arguments: 
sysvar-list - A list of system variables 
values-list - A list of values to set to the system variables 


; Usage: (set-sysvars (list "clayer" "osmode") (list "Plate" @)) 
(defun set-sysvars (sysvar-list values-list / cnt) 

; Set the counter to 0 

(setq cnt 0) 

; Step through each variable and set its value. 

(foreach sysvar sysvar-list 


(setvar sysvar (nth cnt values-list)) 


; Increment the counter 
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(setq cnt (1+ cnt)) 


(princ) 


) 


3. Click File > Save. 


Defining the New createcircle Utility Function 
In Chapter 3, you learned how to modularize the drawplate function into smaller functions 
that can be reused with other functions. These smaller functions were stored in the files named 
drawplate.lsp and utility.lsp. 

The following steps explain how to define a createcircle function that will be used to draw 
a circle near each corner of the rectangle that is drawn with the createrectangle function: 


1. Ifthe utility. lsp file isn’t already open, open the file now in Notepad on Windows or 
TextEdit on Mac OS. 


2. In the text editor area, position the cursor after the last expression in the file and press 
Enter twice. Then type the following; the comments are here for your information and 
don’t need to be typed: 


3; CreateCircle function draws a circle object. 

; 

; Arguments: 

; cenpt - A string or list that represents the center point of the circle 

; rad - A string, integer, or real number that represents the circle's radius 


; Usage: (createcircle "0,0" 0.25) 

; 

(defun createcircle (cenpt rad / old_vars) 
; Store and change the value of the OSMODE and CMDECHO system variables 
(setq old_vars (get-sysvars '("osmode" "cmdecho"))) 


; Disable both OSMODE and CMDECHO 
(set-sysvars '("osmode" "cmdecho") '(0 0)) 


; Draw a circle 
(command "._circle" cenpt rad) 


; Restore the value of the OSMODE and CMDECHO system variables 
(set-sysvars '("osmode" "cmdecho") old_vars) 


) 
3. Click File > Save. 
4. Close Notepad or TextEdit. 
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Revising the drawplate Function 

Now that you have defined the createcircle function in the utility. lsp file, you can update 
the drawplate function to add circles that will represent the bolt holes to the plate. The follow- 
ing steps explain how to update the drawplate. lsp file with the revised drawplate function: 


1. 
2. 


Open the drawplate. lsp file in Notepad on Windows or TextEdit on Mac OS. 


In the text editor area, locate the drawplate function and insert the text in bold font; the 
comments are here for your information and don’t need to be typed: 


; Draws a rectangular plate that is 5x2.75 
(defun c:drawplate ( / ptl pt2 pt3 pt4 width height insPt textValue 


cenPt1 cenPt2 cenPt3 cenPt4 old_vars hole_list) 


3 Store and change the value of the system variables 
(setq old_vars (get-sysvars '("osmode" "clayer" "cmdecho") )) 
(set-sysvars '("osmode" "clayer" "cmdecho") '(0 "0" 0)) 


; Create the layer named Plate or set it current 
(createlayer "Plate" 5) 


; Define the width and height for the plate 
(setq width 5 
height 2.75) 


; Set the coordinates to draw the rectangle 

(setq pt1 '(0 © 0) ;| lower-left corner |; 
pt2 (list width 0 0) ;| lower-right corner |; 
pt3 (list width height 0) ;| upper-right corner | 
pt4 (list 0 height 0)) ;| upper-left corner 


2 


2 


; Draw the rectangle 
(createrectangle pt1 pt2 pt3 pt4) 


; Create the layer named Holes or set it current 
(createlayer "Holes" 1) 


3 Calculate the placement of the circle in the lower-left corner 
3 Calculate a new point at 45 degrees and distance of 0.7071 from pt1 
(setq cenPt1 (polar pt1 (/ PI 4) 0.7071)) 


Calculate the next point from cenPt along the same angle 

as the line drawn between pti and pt2, and 1 unit less 

than the distance between pt1 and pt2 

setq cenPt2 (polar cenPt1 (angle pt1 pt2) (- (distance pt1 pt2) 1))) 


~ we wo ve 


3 Calculate the final two points based on cenPt1 and cenPt2 
(setq cenPt3 (polar cenPt2 (angle pt2 pt3) (- height 1)) 
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cenPt4 (polar cenPt1 (angle pt1 pt4) (- height 1))) 


3 Append all the calculated center points to a single list 
(setq hole_list (append (list cenPt1) 

(list cenPt2) 

(list cenPt3) 

(list cenPt4) )) 


3 Execute the createcircle function for each point 
3 list in the in the hole_list variable 
(foreach cenPt hole_list 

(createcircle cenPt 0.1875) 


; Set the insertion point for the text label 
(setq insPt (list (/ width 2.0) (+ height 0.75) @)) 


; Define the label to add 

(setq textValue (strcat "PLATE SIZE: " 
(vl-string-right-trim " .0" (rtos width 2 2)) 
"y" 
(vl-string-right-trim " .0" (rtos height 2 2)) 


; Create label 
(createlayer "Label" 7) 
(createtext insPt "_c" 0.5 0.0 textValue) 


3; Restore the value of the system variables 
(set-sysvars '("osmode" "clayer" "cmdecho") old_vars) 


3. Click File > Save. 


4. Close Notepad or TextEdit. 


Using the Revised drawplate Function 
Now that that the drawplate. lsp and utility. lsp files have been revised, you must load them 
into AutoCAD before the changes can be used. 

The following steps explain how to load the LSP files into AutoCAD and then start the 
drawplate function: 


1. 


Load the drawplate.lsp and utility. lsp files from the MyCustomF7 les folder, or the 
folder you have them stored in. 


At the Command prompt, type osmode press Enter. Make note of the current running 
object snap value that is returned. 
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3. Check the current value of the clayer and cmdecho system variables, and write down 
their current value. 


4. Type drawplate press Enter. 
5. Type zoom and press Enter, and then type e and press Enter. 


Figure 4.1 shows what the objects should look like in the drawing. A rectangle should be 
drawn starting at the coordinate 0,0 with a width of 5 units and height of 2.75 units. You 
should notice that four circles have also been drawn near each corner of the rectangle. 


FIGURE 4.1 Plate Size: 5x2.75 


Completed plate 


6. Check the values of the osmode, clayer, and cmdecho system variables. Their values 
should be restored to the values you recorded as part of steps 2 and 3. 


Requesting Input and Using 
Conditional and Looping 
Expressions 


Using static values in a custom AutoLISP® program can be helpful in automating tasks, but it 
also limits the functionality that can be introduced by custom AutoLISP programs. Using static 
values doesn’t give the user the ability to specify a custom value, such as the insertion point of a 
block or which objects to modify. AutoLISP provides many functions that allow you to request 
input at the Command prompt or with controls in a dialog box. I cover working with dialog 
boxes in Chapter 13, “Implementing Dialog Boxes (Windows only).” 

When requesting input from a user, you should verify the input provided from the user 
before acting upon it. Comparison and logical grouping operators can be used to create test 
conditions and validate a value or grouping of values. Test conditions can be used to control 
which expressions are executed or specify the number of times a set of AutoLISP expressions 
might be executed as part of a looping expression. 

In this chapter, you will learn to get input at the Command prompt and provide information 
back to the user in the form of messages. Additionally, you will learn to use conditional and 
looping expressions to perform actions based on the result of a test condition. 


Interacting with the User 


You've learned that you can use the PAUSE predefined variable with the command function to 
allow the user to provide a value. PAUSE works great for providing a response to the current 
prompt of the active command, but it is also a limitation. Any value provided in response 
to PAUSE is passed directly to the command and can’t be captured or manipulated by your 
AutoLISP program. 

There will be times when using PAUSE with the command function isn’t enough for your pro- 
grams. The AutoLISP programming language contains several functions that are available for 
requesting input. The values returned by the user can then be validated using test conditions. 

I explain how to create test conditions with comparison and logical grouping operators later, in 
the “Conditionalizing and Branching Expressions” section. 

In addition to getting input from the user, a custom program can provide feedback to the 
user, letting them know the current state of a program or when an error occurred. Feedback can 
be of two different types: textual and graphical. Textual feedback can be in the form of messages 
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at the Command prompt or in a message box, whereas graphical feedback might be temporary 
graphics drawn in the drawing area. 


Requesting Input at the Command Prompt 


AutoLISP provides functions that allow you to request input from the user at the Command 
prompt. Input requested can be any of the following: 


+» ©% ¢ o 


Integer 

Real 

String or keyword 

2D point or 3D point list 

Object or entity name (see Chapter 6, “Creating and Modifying Graphical Objects”) 


Before requesting input from the user, you want to define a prompt that should be displayed 
with the request for input. Prompts are short text messages that give the user an idea what type 
of input is expected and whether any options are available. I discuss recommended etiquette to 
use when creating a prompt in the sidebar “Guidelines for Prompts.” 

This exercise shows how to draw a plan-view representation of a window based on input 
from the user: 


1. 


At the AutoCAD Command prompt, type (setq cur_osmode (getvar "osmode")) and 
press Enter to store the current value of the osmode system variable. 


Type (setvar "osmode" 0) and press Enter. 


3. Type (setq width (getreal "\nEnter window width: ")) and press Enter. 


12. 


At the Enter window width: prompt, type 36 and press Enter to specify the width for 
the window that will be drawn. 


Type (setq wall_thickness (getreal "\nEnter wall thickness: ")) and press 
Enter. 


At the Enter wall thickness: prompt, type 6 and press Enter to set the depth of the 
window. 


Type (setq base (getpoint "\nSpecify base point: ")) and press Enter. 


At the Specify base point: prompt, specify a point in the drawing area at which to 
start drawing the window. 


Type (setq ang (getangle base "\nSpecify rotation: ")) and press Enter. 


. At the Specify rotation: prompt, specify an angle of rotation for the window. 


. Type (setq strPt (polar base (+ ang (/ PI 2)) (/ wall_thickness 2))) and 


press Enter to calculate the midpoint of the window for the start point of the line that will 
represent the class in the window. 


Type (setq endPt (polar strPt ang width) ) and press Enter to calculate the end- 
point of the line that will represent the class in the window. 
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13. Type (command "._rectang" base "_r" (* (/ ang PI) 180) "_d" width wall_ 
thickness endPt) and press Enter to draw the outline of the window in plan view. 


14. Type (command "._line" strPt endPt "") and press Enter to draw the line that repre- 
sents the glass in the window. 


15. Type (setvar "osmode" cur_osmode) and press Enter to restore the previous value of 
the osmode system variable. 


Figure 5.1 shows the results after you complete all the steps in this exercise. 


FIGURE 5.1 
Window drawn 
based on user input 


GETTING NUMERIC VALUES 


Numbers play an important role in creating and modifying objects in a drawing, whether 
it is the radius of a circle or the number of rows in a rectangular array. As I mentioned in 
Chapter 2, “Understanding AutoLISP,” AutoLISP supports two types of numbers: integers and 
reals. Integers are whole numbers without a decimal value, and reals are numbers that support a 
decimal value. You can use the AutoLISP getint and getreal functions to request either 
an integer or real number value at the Command prompt. The entered number is the value 
returned by the function, but if the user presses the spacebar or Enter without providing a 
value, nil is returned. When an incorrect value is provided, the function re-prompts the user to 
enter a correct value. 

The following shows the syntax of the getint and getreal functions: 


(getint [prompt]) 
(getreal [prompt]) 


The prompt argument represents the textual message to display at the Command prompt 
when the expression is evaluated. The prompt argument is optional, but I recommend always 
providing one. 

The following are examples of the getint and getreal functions, and the values that are 
returned: 


(getint) 
Type 1.25 and press Enter 
Requires an integer value. 
Type 1 and press Enter 
I 


(getint) 
Press Enter 
nil 


(setq segments (getint "\nEnter number of line segments: ")) 
Enter number of line segments: Type 3 and press Enter 
3 
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(getreal) 
Type 1.25 and press Enter 
1525 


(getreal) 
Type 1 and press Enter 
1.0 


(setq rotation (getreal "\nEnter angle of rotation: ")) 
Enter angle of rotation: Type 22.5 and press Enter 
22,5 


GETTING POINT LIST VALUES 


Point lists are used to represent 2D and 3D coordinate values in a drawing. The AutoLISP get- 
point function allows the user to pick a point in the drawing area based on an optional base 
point or type a coordinate value at the Command prompt. When an optional base point is 
provided, a rubber-band line is drawn from the base point to the current position of the cursor. 
Figure 5.2 shows the rubber-band line effect used when getting a point based on the optional 
base point. The specified point is returned by the function, but if the user presses the spacebar 
or Enter without providing a value, nil is returned. 


FIGURE 5.2 Rubber-band line 
Rubber-band line 

effect used when 

specifying a point 


from a base point [Command: | [2s] 
Base point =] 


The following shows the syntax of the getpoint function: 
(getpoint [base_point] [prompt]) 


Its arguments are as follows: 


base_point The base_point argument determines if a rubber-band line is drawn from the 
current position of the cursor to the coordinate value specified by the base_point argument. 
The base_point argument is optional. 


prompt The prompt argument represents the textual message to display at the Command 
prompt when the expression is evaluated. The prompt argument is optional, but I recom- 
mend always providing one. 


The following are examples of the getpoint function and the values that are returned: 
(getpoint) 
Pick a point in the drawing area or enter a coordinate value 


(12.5 10.0 0.0) 


(setq pt1 (getpoint "\nSpecify first point: ")) 
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Specify first point: Pick a point in the drawing area 
(4.5 9.5 0.0) 


(setq pt2 (getpoint pt1 "\nSpecify next point: ")) 
Specify next point: Pick a point in the drawing area 
(11.0 13.5 0.0) 


In addition to the AutoLISP getpoint function, the getcorner function can be used to 
request a point. There are differences between the getpoint and getcorner functions, though, 
which are as follows: 


@ The getcorner function requires a base point. 


@ The getpoint function draws a rubber-band line from a base point to the cursor, whereas 
the getcorner function draws a rectangle from the base point to the cursor, as shown in 


Figure 5.3. 
PIGURE 3:3 = Cursor location 
The rubber-band 
effect used when are ae 


specifying the 

opposite corner 

with the getcorner 

function Base point — 


The following shows the syntax of the getcorner function: 
(getcorner base_point [prompt]) 


Its arguments are as follows: 


base_point The base_point argument specifies the base point, which is used to define one 
corner of the rectangle that is displayed when dragging the cursor. 


prompt The prompt argument represents the textual message to display at the Command 
prompt when the expression is evaluated. The prompt argument is optional, but I recom- 
mend always providing one. 


The following is an example of the getcorner function and the value that is returned: 


(setq pt1 (getpoint "\nSpecify first corner: ")) 
Specify first corner: Pick a point in the drawing area 
(3.5 6.0 0.0) 


(setq pt2 (getcorner pt1 "\nSpecify opposite corner: ")) 
Specify opposite corner: Pick a point in the drawing area 
(12.5 12.5 0.0) 


GETTING DISTANCE AND ANGULAR VALUES 


While the AutoLISP getreal function can be used to request a distance or angular value, 
AutoLISP contains several functions to acquire a distance or angular value from the drawing 
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area. The following explains the functions that can be used to request a distance or angular 
value from the Command prompt. 


getdist 


The getdist function accepts an optional base point and prompt, just like the getpoint func- 
tion does. Instead of returning a point list like the getpoint function, getdist returns a real 
number that represents the distance between the two points or the value the user typed. If the 
user presses Enter without providing a value, the getdist function returns nil. 

The following are examples of the getdist function: 


(getdist) 

Pick a point in the drawing area, enter a coordinate value, or enter a distance 
Specify second point: If a point was specified, pick or enter a second point 
6.80074 


(setq pt1 (getpoint "\nSpecify first point: ")) 
Specify first point: Pick a point in the drawing area 
(8.0 8.0 0.0) 


(setq dist (getdist pt1 "\nSpecify second point: ")) 
Specify second point: Pick a point in the drawing area 
7.0 


NOTE The current value of the Lunits system variable affects the values the getdist func- 
tion can accept from the user when entered at the Command prompt instead of specifying two 
points. The getdist function always accepts decimal values and the formatting expressed by 
the value of Lunits. 


The following examples show how the lunits system variable affects the value returned by 
the getdist function: 


; Set LUNITS to 2 (decimal units) 
(setvar "Lunits" 2) 


(getdist) 
Type 15 and press Enter 
15.0 


(getdist) 
Type 1'-3" or 1'3", and press Enter 
Requires numeric distance or two points. 


; Set LUNITS to 4 (archiectural units) 
(setvar "Lunits" 4) 
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(getdist) 
Type 1'-3" and press Enter 
15.0 


TIP You can use the distof function to convert to a real number a string that is formatted as 
one of the supported linear distance formats. You can also use the rtos function to convert 
a real number to a formatted linear distance string when you want to add a real value that is 
stored in a variable to a prompt or message. For example, if you want the previous value to be 
displayed in a prompt, you must convert the value to a string before concatenating the value 
with a long string. I discussed the distof and rtos functions in Chapter 3, “Calculating and 
Working with Values.” 


getangle 


The getangle function accepts an optional base point and prompt, just like the getpoint and 
getdist functions do. Instead of returning a point list or a distance value, getangle returns a 


real number that represents the angle of measurement expressed in radians between two points. 
The user can also enter an angular value based on the current units of the drawing; the entered 
value is converted to and returned as radians. The aunits system variable determines the cur- 


rent angular units for the drawing. 


The value returned by the getangle function, whether specified by picking points or entered 
directly at the Command prompt, is affected by the angdir system variable. If the user presses 


Enter without providing a value, the getangle function returns nil. 
The following are examples of the getangle function: 


(getangle) 

Pick a point in the drawing area, enter a coordinate value, or enter an angle 
Specify second point: If a point was specified, pick or enter a second point 
0.605545 


(getangle "\nEnter angle: ") 
Enter angle: Type 45 and press Enter 
0.785398 


(setq pt1 (getpoint "\nSpecify first point: ")) 
Specify first point: Pick a point in the drawing area 
(5.5 6.5 0.0) 


(setq rad (getangle pt1 "\nSpecify second point: ")) 
Specify second point: Pick a point in the drawing area 
0.885067 


NOTE The current value of the aunits system variable affects the value that can be entered 
at the Command prompt by the user—not specified by two points—when the getangle and 
getorient functions are used. For example, entering 45 is not the same for decimal, gradian, 
and radian angular units. 
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The following examples show how the aunits system variable affects the value returned by 
the getangle function: 


; Set AUNITS to © (decimal degrees) 
(setvar "aunits" 0) 


(getangle) 
Type 45 and press Enter 
0.785398 


; Set AUNITS to 2 (gradian units) 
(setvar "aunits" 2) 


(getangle) 
Type 45 (45 decimal degrees) and press Enter 
0.706858 


(getangle) 
Type 50g (45 degrees) and press Enter 
0.785398 


TIP You can use the angtof function to convert a string that is formatted as one of the sup- 
ported angular formats to a real number. You can also use the angtos function to convert a 
real number to a formatted angular string so the value can be displayed as part of a prompt or 
message to the user. I discussed the angtof and angtos functions in Chapter 3. 


getorient 


The getorient function accepts an optional base point and prompt, and it’s similar to the 
getangle function. The value returned by the getorient function is a real number that repre- 
sents the angle of measurement expressed in radians between two points. The returned value 
can also be based on an angular value entered in the current units of the drawing; the entered 
value is converted to radians. The aunits system variable determines the current angular units 
for the drawing. 

The value returned by the getorient function is affected by the angdir and angbase system 
variables. The angle returned by getorient is the value provided by the user plus the value of 
the angbase system variable. For example, changing angbase to 45 and entering a value of 0 for 
the getorient function returns a value of 0.785398, which is the current value of angbase. If the 
user presses Enter without providing a value, the getorient function returns nil. 

The following are examples of the getorient function: 


(getorient) 

Pick a point in the drawing area, enter a coordinate value, or enter an angle 
Specify second point: If a point was specified, pick or enter a second point 
0.785398 
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(getorient "\nEnter angle: ") 
Enter angle: Type 45 and press Enter 
0.785398 


(setq pt1 (getpoint "\nSpecify first point: ")) 
Specify first point: Pick a point in the drawing area 
(5.5 6.5 0.0) 


(setq rad (getorient pt1 "\nSpecify second point: ")) 
Specify second point: Pick a point in the drawing area 
0.885067 


The following steps demonstrate the effect of the angdir and angbase system variables on 
the getangle and getorient functions: 


1. At the AutoCAD Command prompt, type (setq cur_angdir (getvar "angdir")) and 
press Enter. 


Type (setq cur_angbase (getvar "angbase") ) and press Enter. 
Type angdir and press Enter, and then type 0 and press Enter. 
Type angbase and press Enter, and then type ® and press Enter. 


Type (getangle) and press Enter. 


Bw ew ON 


Type 45 and press Enter. 

0.785398 is returned, which is the same as 45 degrees in radians. 

7. Type (getorient) and press Enter, and then type 45 and press Enter. 
0.785398 is returned. 

8. Type angdir and press Enter, and then type 1 and press Enter. 


Changing angdir switches the direction in which angles are calculated, from counter- 
clockwise to clockwise. 


9. Type (getangle) and press Enter, and then type 45 and press Enter. 


5.49779 is returned because the direction in which angles are measured has been 
changed. Typing 315 would be the same as entering 45 degrees in step 6. 


10. Type (getorient) and press Enter, and then type 45 and press Enter. 
5.49779 is returned. 

11. Type angdir and press Enter, and then type 0 and press Enter. 

12. Type angbase and press Enter, and then type 45 and press Enter. 


13. Type (getangle) and press Enter, and then type 45 and press Enter. 
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14. 


15. 
16. 


0.785398 is returned because the value returned by the getangle function is always 
based on the x-axis of the world coordinate system (WCS). 


Type (getorient) and press Enter, and then type 45 and press Enter. 


1.5708 is returned because the value returned by the getorient function is always 
based on the snapbase system variable. 


Type (setvar "angdir" cur_angdir) and press Enter. 


Type (setvar "angbase" cur_angbase) and press Enter. 


Listing 5.1 is a set of custom functions that can be used to convert radians to degrees and 
degrees to radians. 


LISTING 5.1: Radians to degrees and degrees to radians 


; Convert Radians to Degrees 
; Usage: (rtd 0.785398) 
(defun rtd (rad) 

(* (/ rad PI) 180) 


; Convert Degrees to Radians 
; Usage: (dtr 45.0) 
(defun dtr (deg) 

(* deg (/ PI 180)) 


) 


GUIDELINES FOR PROMPTS 


Prompts are used to help explain the type of data that is being requested along with how that data 
might be used. Most of the commands you start in AutoCAD that don’t open a dialog box display a 
prompt that follows a common structure. I recommend structuring your prompts list like the ones 
you see in AutoCAD commands to make your prompts feel familiar to the user. Prompts commonly 
have two or more of the following elements: 


Message The message is typically formatted as a statement that begins with a verb, such 
as specify or enter. I recommend using Speci fy when the user can pick one or more points in 
the drawing area to define a value or enter a value, and using Enter when the user can only 
type a value at the Command prompt. Messages can also be formatted as questions, but this 
is much less common. I recommend avoiding a conversational tone in the message, which 
means avoiding words such as please and thanks. Control sequences can also be used as part 
of a message; \n forces the text that follows it onto a new line, and \\ and \" represent the 
backslash and quotation mark characters, respectively. For a full list of supported control 
sequences, search on the “prin1 function” in the AutoLISP Help system. 
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Option List The option list identifies which keywords are available in addition to the 
main data type of the getxxx function. An opening ( [ ) and a closing ( ] ) square bracket 
denote the start and end of the option list. Each keyword in the option list should be sepa- 
rated by a forward slash (/), and the capitalization should match that of the keywords listing 
in the initget function that is evaluated just prior to the next getxxx function. The option 
list should come after the main message of the prompt. I discuss the initget function in 
the “Initializing User Input and Keywords” section later in this chapter. 


Default Value The default value that should be used if the user doesn’t provide a value 
before pressing Enter is commonly displayed in a set of angle brackets (<> ). The get xxx 
function doesn’t automatically return the value in the angle brackets if Enter is pressed 
before a value is provided. You must handle checking for a nil or empty string ("") value 
and return the desired default value instead. I demonstrate how to implement a prompt with 
a default value in the “Testing Multiple Conditions” section later in this chapter. 


Colon A colon should be the last character in a prompt, followed by a space to provide 
some separation between the prompt and the value entered by the user. 


The following is the recommend structure of a prompt: 


Message [Option list] <Default value>: 


The following are examples of different prompts that follow my recommendations: 


"\nSpecify next point: " 
"\nSpecify rotation or [Reference] <45.000>: " 
"\nEnter a number or press Backspace to clear: " 


"\nEnter color option [Blue/Green/Red] <Blue>: " 


The following are examples of prompts that shouldn't be used: 


"\nNext point: " 
"\nPick a color (blue green black) :" 
"\nSpecify next point" 


"\nEnter color option or <Blue> [Blue/Green/Red]: " 


GETTING STRING VALUES 


String values are used to represent the prompts that should be displayed when requesting 
input, a block name or path, and even the text to be added to an annotation object. You can use 
the getstring function to request a string value at the Command prompt and specify whether 
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spaces are allowed in the string returned. The entered string is returned by the function, but if 
the user presses Enter without providing a value, an empty string ("") is returned. 
The following shows the syntax of the getstring function: 


(getstring [allow_spaces] [prompt]) 


Its arguments are as follows: 


allow_spaces The allow_spaces argument determines if the spacebar acts like the Enter 
key or if it allows the entering of a space character. By default, pressing the spacebar is the 
same as pressing Enter. You can provide a value of T to allow the user to enter a space charac- 
ter, or nil to not allow spaces in the text entered. A conditional expression that evaluates to T 
or nil can also be used. The allow_spaces argument is optional and the argument defaults 
to nil when a value isn’t provided. 


prompt The prompt argument represents the textual message to display at the Command 
prompt when the expression is evaluated. The prompt argument is optional, but I recom- 
mend always providing one. 


The following are examples of the getstring function and the values that are returned: 


(getstring) 
Type 1.25 and press Enter 
"7.25" 


(getstring) 


Press spacebar 
we 


(getstring T "\nEnter your name: ") 
Type your first and last (or family) name, then press Enter 
"Lee Ambrosius" 


INITIALIZING USER INPUT AND KEYWORDS 


The behavior of the getxxx functions can be modified with the initget function. When you 

want to enable one or more of the alternate behaviors of a getxxx function, you include the 

initget function before getxxx. In addition to alternate behaviors that can be enabled, many of 

the getxxx functions can accept keywords that you set up using the initget function as well. 
The following shows the syntax of the initget function: 


(initget [flags] [keyword_list]) 


The flags argument represents a bitcoded value that controls the type of input a getxxx 
function can accept. The flags argument is optional, but when provided can contain one or 
more of the bits described in Table 5.1. 


TABLE 5.1: 


BITCODE 


1 


2 


16 


32 


64 


128 


256 


512 


1024 
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initget flags argument bitcodes 


DESCRIPTION 


User is not allowed to press Enter without first providing a value. 
Zero can't be entered when requesting a numeric value. 
A negative value can't be entered when requesting a numeric value. 


The point can be specified outside of the drawing’s limits; determined by the Limcheck 
system variable. 


This bitcode is no longer in use. 


Rubber-band lines and rectangular boxes are shown as dashed instead of the default 
setting as solid. 


Coordinate input is restricted to 2D points. 


Arbitrary input is allowed; text values can be entered when using any of the get xxx 
functions. 


Direct distance input takes precedence over arbitrary input. 


Allows the use of temporary user coordinate systems (USCs) when the cursor passes 
over the edge of a face ona solid that is planar. 


Z-coordinate values are disabled. 


For more information on the flags that are available, search on the keywords “initget func- 
tion” in the AutoCAD Help system. 

The keywords_list argument represents the keywords that the next getxxx function can 
support. The keywords must be placed in a string and each separated by a space. The letters 
you want a user to be able to enter without typing the full keyword must be in uppercase, and I 
recommend that they be consecutive; all other letters in a keyword must be lowercase. The key- 
words_list argument is optional. Examples of keyword lists are "Blue Green Red" and "Azul 
Verde Rojo_Blue Green Red". The second list represents a keyword list that supports both a 
localized language and a global language; here the localized language is Spanish and typically 
the global language is English. 

The global language value is used when an underscore is placed in front of a letter combina- 
tion or command name at the Command prompt. Global language support typically is impor- 
tant for supporting a single command macro in user-interface elements and when others use 
your custom functions with their own custom programs. For example, typing A for the Azul 
option when the Spanish-language version of your program was loaded would work just fine 
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but would fail if the English version was loaded. Entering _B instead would work with either 
the Spanish or English version of the program. 

The following are examples of the initget function used with some of the getxxx functions, 
and the values that are returned: 


; Disables pressing Enter without first entering a number or Diameter keyword 
(initget 1 "Diameter") 

(setq val (getdist "\nSpecify radius or [Diameter]: ")) 

Specify radius or [Diameter]: Type D and press Enter 

"Diameter" 


(initget 1 "Diameter") 

(setq val (getdist "\nSpecify radius or [Diameter]: ")) 
Specify radius or [Diameter]: Type 2.75 and press Enter 
2.75 


(initget 32) 

(setq pt1 '(0 © 0)) 

(setq pt2 (getcorner pt1 "\nSpecify opposite corner: ")) 
Specify opposite corner: Pick a point in the drawing area 
(12.5 12.5: 0.0) 


(initget 7) 

(setq num (getint "\nEnter a number: ")) 
Enter a number: Type -1 and press Enter 
Value must be positive and nonzero. 
Enter a number: Type 4 and press Enter 
4 


NOTE All getxxx functions except the getstring function support keywords, and the bitcode 
1 value of the initget function doesn’t apply to getstring. 


In addition to using keywords with the getxxx functions, you can use the getkword func- 
tion. The getkword function accepts input only in the form of a keyword value unless arbitrary 
input is enabled with the 128 bitcode of the initget function; in that case, the function can 
accept any string input. The getkword function can return only a string value—it can’t return 
numbers or point lists. The initget function must be used to set up the keywords that the 
getkword function can accept. 

The following shows the syntax of the getkword function: 


(getkword [prompt]) 


The prompt argument represents the textual message to display at the Command prompt 
when the expression is evaluated. The prompt argument is optional, but I recommend always 
providing one. 

The following are examples of the getkword function and the values that are returned: 


(initget "Yes No") 
(getkword "\nErase all block references [Yes/No]: ") 
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Erase all block references [Yes/No]: Type H and press Enter 
Invalid option keyword. 

Erase all block references [Yes/No]: Type Y and press Enter 
"Yes" 


(initget "LTYpe LWeight LTScale") 

(getkword "\nChange object property [LTYpe/LWeight/LTScale]: ") 
Enter option [LTYpe/LWeight/LTScale]: Type L and press Enter 
Ambiguous response, please clarify... 

LTYpe or LWeight or LTScale? Type LW and press Enter 
"LWeight" 


NOTE When supporting keywords, you will need to use test conditions and conditional state- 
ments to determine how your program should handle the keyword the user chose. I discuss 
these concepts in the “Conditionalizing and Branching Expressions” section later in this chapter. 


DEFINING CUSTOM USER-INPUT FUNCTIONS 


The AutoLISP getxxx functions should cover most input needs from the Command prompt, but 
there might be times when you want more control over the type of input and return value. The 
grread function provides access to the raw input values that are provided with the keyboard 
(physical or virtual) or pointing device (mouse, trackpad, touchscreen, tablet, and other sup- 
ported devices). Raw input includes, but is not limited to, keypresses, the current location of the 
crosshairs, or which button is pressed on the pointing device. 

The grread function returns a list with the input that is represented by the device. The first 
value in the list that grread returns represents the type of input that the user provided, and the 
second value represents the input collected. The input collected might be a list or integer value. 
Table 5.2 presents a few examples of values returned by the grread function and their meaning. 


TABLE 5.2: Example grread returns 
VALUES DESCRIPTION 
(2 65) 2 indicates that the user pressed a key on the keyboard; the remain- 


ing value indicates that the key that was pressed is represented by 
the ASCII value of 65, capital A. 


(3 (11.0 9.5 0.0)) 3 indicates that the user clicked in the drawing area; the remaining 
values indicate that at the time of the click the cursor was located at 
the coordinate value of 11,9.5. 


(25 380) 25 indicates that the user right-clicked or secondary-clicked in the 
drawing area, and at the time of the click the cursor was located 
380 pixels from the left side of the screen. 
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You can learn more about the return values of the grread function by doing a search on 
“erread function” in the AutoCAD Help system. 
The following shows the syntax of the grread function: 


(grread [tracking [input_type [cursor_type]]]) 


Its arguments are as follows: 


tracking The tracking argument determines if coordinates are returned when the cursor 
is moved. Use a value of T to enable tracking when the cursor is moved; otherwise, provide 
nil. The tracking argument is optional. 


input_type The input_type argument represents a bitcoded value that controls the type of 
input grread can accept. The input_type argument is optional. 


cursor_type The cursor_type argument represents the type of cursor that should be active 
while the grread function is waiting for input. The input_type argument must contain the 

2 bitcode value to change the cursor to the one specified by the cursor_type argument. The 
cursor_type argument is optional. 


For more information on the values that can be used with the input_type and cursor_type 
arguments, search on “grread function” in the AutoCAD Help system. 
The following are examples of the grread function and the values that are returned: 


(grread) 
Click the pick (left) button in the drawing area 
(3 (22.704 7.70166 0.0)) 


(grread) 
Press the P key on the keyboard 
(2 112) 


Listing 5.2 shows a custom function that gets raw input from the keyboard and continues 
prompting for input as long as neither the spacebar nor the Enter key has been pressed. The way 
the input and conditionals are set up, only the number and the Backspace key are valid input. 
When valid input is provided, the number pressed is stored as a string in a user variable named 
number and an * (asterisk) is displayed at the Command prompt in its place. 


LISTING 5.2: PIN or search code input function 


; Function limits input to number, Backspace, Enter, and spacebar keys. 
; Valid input is also masked with the use of the * (asterisk) character. 
(defun c:MyPINCode ( / number code ch) 


; Display a prompt to the user since 
; grread does not display a prompt 


(prompt "\nEnter number [backspace to clear]: ") 


; Request input from the user 
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(setq code (grread) number "") 


3; Check to see if the user pressed a key on the keyboard 
; and continue requesting characters until Enter or spacebar is pressed, 
; or a non-keypress occurs. 
(while (and (= 2 (car code)) 
(and (/= 13 (cadr code) ) 
(/= 32 (cadr code) ))) 
(if (and (>= (cadr code) 48) 
(<= (cadr code) 57)) 
(progn 
(setq ch (chr (cadr code))) 
(setq number (strcat number ch)) 
(prince "*") 


; Enables the use of Backspace to clear the current 
; value entered and the number of *s displayed at 
; the command-line window. 
(if (= (cadr code) 8) 
(progn 
(repeat (strlen number) 
(princ (chr 8)) 
) 


(setq number "") 


33; Ask for more input if the user did not press Enter or Space 
(if (or (/= 13 (cadr code))(/= 32 (cadr code))) 
(setq code (grread) ) 


; Display the actual numbers entered 
(prompt (strcat "\nPIN entered was: " number) ) 
(princ) 


) 


I explain more about the prompt and princ functions in the next section, and I discuss the if 
and while functions along with comparison and logical grouping operators later in this chapter. 


Providing Feedback to the User 


Although a program can simply request information and then go on its way, it is best to 
acknowledge the user and provide them with some feedback. Now, this doesn’t mean you need 
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to make small talk with the person on the other side of the screen, but it also doesn’t mean you 
should share your life story. Based on the tasks your AutoLISP program might perform, you 
may want to provide information to the user when the function does any of the following: 


Starts Consider displaying the default settings or options that your program will be using, 
similar to the informational text that is displayed before the first prompt when using the 
fillet or style command. 


Executes When processing a large data set or number of objects, consider displaying a 
counter that helps the user know that something is still happening. 


Causes an Error If something happens internally in your program, you should let the user 
know what went wrong so they can report the problem or try to fix it themselves. 


Completes In most cases, you don’t need to display information when your function 

is done executing, simply because the user is returned to an empty Command prompt. 
However, you might want to let the user know if the information from a set of objects was 
successfully extracted or how many objects were modified. 


The following sections cover the AutoLISP functions that can be used to display messages to 
the user at the Command prompt, in a message box, or at the status bar. 


DISPLAYING MESSAGES AT THE COMMAND PROMPT 


In the “Requesting Input at the Command Prompt” section earlier, you learned how to display 
a message when requesting input from the user with one of the getxxx functions. Using the 
AutoLISP prompt function, you can also display messages to the user without requesting input. 
The prompt function simply displays a message at the Command prompt. 

The following shows the syntax of the prompt function: 


(prompt message) 


The message argument represents the textual message to display at the Command prompt. 
As part of the textual message, you can use the control sequence \n to force the message on a 
new line and use the control sequences \\ and \" to represent a backslash and quotation mark 
characters, respectively. For a full list of supported control sequences, search on “prin1 func- 
tion” in the AutoCAD Help system. 

The following are examples of the prompt function and the values that are returned: 


(prompt (strcat "\nCurrent OSMODE value: " (itoa (getvar "OSMODE") ))) 
Current OSMODE value: 4133 


(prompt "\nDrawing Name: ") (prompt (getvar "DWGNAME") ) 
Drawing Name: Drawing1.dwg 


Optionally, you can use the terpri function to force messages displayed at the command- 
line window to a new line. The results are just like using the \n control sequence as part of 
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the textual message passed to the prompt function. The terpri function doesn’t accept any 
arguments. 


The following is an example of the terpri function: 


(prompt "\nDrawing Name: ") 
(terpri) 

(prompt (getvar "DWGNAME") ) 
Drawing Name: 
Drawing1.dwg 


In addition to the prompt function, the princ, prini, and print functions can be used to dis- 
play the values of any type of data, not just strings, at the command-line window. These three 
functions are similar to each other, but have the following differences: 


@ Theprincand prini functions are similar, with the exception of how control sequences 
are handled, such as \n and \\. Control sequences in messages aren't expanded with the 
princ function, but they are with the prin1 function. 


@ Thepriniand print functions are similar, with the exception of a space character being 
placed before the value that is returned by the function. The prini function doesn’t 
include a space character before the value that is returned, but the value returned by the 
print function does. 


The following shows the syntax of the princ, prini, and print functions: 


(princ [atom [file_descriptor] ]) 
(prinl [atom [file_descriptor] ]) 
(print [atom [file_descriptor]]) 


The arguments are as follows: 


atom The atomargument represents the value to output to the Command prompt or the 
external file. The atom argument is optional. 


file_descriptor The file_descriptor argument represents the pointer to the file that 
has been opened with the open function. You'll learn how to work with external files in 
Chapter 8, “Working with the Operating System and External Files.” 


The following are examples of using the princ, prini, and print functions, and the values 
that they return: 


(princ "\nSample message") 
Sample message"\nSample message" 


(prini "\nSample message") 
"\nSample message""\nSample message" 


(print "\nSample message") 
"\nSample message" "\nSample message" 
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TIP = The princ function can be used to exit a custom function quietly. Exiting a function quietly 
means that the function doesn’t return the value of its last expression. I explained how to exit 
quietly from a custom function in Chapter 3. 


DISPLAYING MESSAGES IN A MESSAGE BOX OR AT THE STATUS BAR 


Displaying messages at the Command prompt or command-line window are the most common 
ways to display information back to the user with AutoLISP. However, you can also display mes- 
sages in a message box (which the user must acknowledge before the AutoLISP program contin- 
ues) or on the status bar. 

The AutoLISP alert function displays a simple message box with a custom message and 
only an OK button. If you are developing AutoLISP programs for AutoCAD on Windows, you 
can use Dialog Control Language (DCL) to create a custom error message that lets you display 
both an OK and a Cancel button. Chapter 13 discusses DCL. 

The following shows the syntax of the alert function: 


(alert message) 


The message argument represents the textual message you want to display in the message 


box. 
The following is an example of the alert function. Figure 5.4 displays the results of the 
example code. 


(alert "Error: No value provided.") 


FIGURE 5.4 AutoCAD Message 
Message displayed 


with the alert 


. Error: No value provided. 
function 


On Windows, if you have Express Tools installed, you can use the AutoLISP 
acet-ui-message function to display a message box with more options than the alert 
function. Figure 5.5 shows an example of a message box displayed with the acet-ui-message 
function. The acet-ui-message function returns an integer value based on the button the user 
clicks in the message box. 


FIGURE 5.5 AutoCAD Platform Customization 
Custom message 


displayed with the 
acet-ui-message 
function 


Custom message using ACET-UI-MESSAGE 


Cancel 


FIGURE 5.6 
Message displayed 
in the status bar 
with the grtext 
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The AutoLISP expression that displays the message box shown in Figure 5.5 is as follows: 


(acet-ui-message "Custom message using ACET-UI-MESSAGE" 
"AutoCAD Platform Customization" 1) 


If you are using AutoCAD on Windows, you can also display a message in the status bar. The 
messages you display in the status bar should be kept short and simple. A message can be dis- 
played in the status bar using the grtext function. 

The following shows the syntax of the grtext function: 


(grtext location message) 


Its arguments are as follows: 


location The location argument represents where the textual message should be dis- 
played. In early AutoCAD releases on Windows, location allowed you to display text in a 
user interface called the Screen menu, which has since been discontinued. Use the -1 value to 
specify the status bar as the location for the textual message. 


message The message argument represents the textual message to display at the status bar. 


The following is an example of the grtext function. Figure 5.6 displays the results of the 
example code. 


(grtext -1 "Error: No value provided.") 


|. E 
I, 41> [PIi Model { Layout] / Layout2 


Pass the grtext function an empty string ("") to remove the recent message from the 
status bar: 


(grtext -1 "") 


NOTE On Mac OS, the grtext function doesn’t cause an error when used; it also does not 
display the message that was passed to the function. 


EXPANDING OR SHOWING THE COMMAND-LINE HISTORY 


The command-line window normally displays three lines of history, which isn’t ideal for long 
prompts or messages. The AutoLISP textscr or textpage functions allow you to expand the 
command-line window or show the AutoCAD Text window, similar to using the ? option of 

the setvar command, to make it easier to view long messages. The AutoCAD Text window is 
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available in AutoCAD on Windows only when the command-line window is docked; it is not 
available when the command-line window is in its default floating state. The textscr and text- 
page functions don’t accept any arguments. 


Working with the Graphics Windows 

Feedback to the user doesn’t need to be limited to just textual messages; you can draw tempo- 
rary graphics in the drawing area to communicate problems or show where permanent graphi- 
cal objects might be created. Temporary graphics aren't created using the standard AutoCAD 
commands, and there is no way to convert temporary graphics to permanent graphical objects 
that can be stored with a drawing. Since the temporary graphics aren't part of the draw- 

ing, changing the view with the zoom or pan command, or regenerating (regen command) or 
redrawing (redraw command) the display removes any temporary graphics that were drawn. 


DISPLAYING TEMPORARY VECTORS IN THE DRAWING AREA 


Temporary graphics allow you to visually communicate to the user how large an object is or 
where it might be placed prior to adding the object to a drawing. The graphics that you can 
draw in the graphics area are limited to line segments only; curves aren’t supported. If you 
need to draw a curve, you must calculate the points along an arc or circle, and then draw the 
object using line segments. Individual line segments can be drawn using the AutoLISP grdraw 
function. 

The following shows the syntax of the grdraw function: 


(grdraw vec_from vec_to vec_color [vec_highlight]) 


Its arguments are as follows: 


vec_from The vec_fromargument represents the coordinate value that the vector should 
start at. 


vec_to The vec_to argument represents the coordinate value that the vector should be 
drawn to. 


vec_color The vec_color argument represents the AutoCAD Color Index (ACI) color value 
that the vector should be assigned. Individual vectors can be removed from the display by 
drawing a new vector with the color value of -1 over the top of the vector you want to remove. 


vec_highlight The vec_highlight argument represents the highlighting of the vector 
(which is normally dashed). The vec_highlight argument is optional and it is an integer 
value. Typically, a value of 1 is used to display the vector as a dashed line. In AutoCAD on 
Windows or Mac OS, only dashed lines are supported; earlier AutoCAD releases designed for 
other platforms supported different highlighting behaviors. 


The following are examples of drawing vectors in the drawing area with the grdraw func- 
tion. The results of the examples are shown in Figure 5.7. 


; Draws a vector from 0,0 to 5,5 with a ACI color of 32 and dashed 
(grdraw '(0 ©) '(5 5) 32 1) 
nil 


; Draws a vector from 5,0 to 0,5 with a ACI color of 150 
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(grdraw '(5 0) '(0 5) 150) 
nil 


FIGURE 5.7 Pa 
Drawing individual a“ 
vectors with the 4 


grdraw function ra bs 


In addition to drawing vectors one at a time, you can draw multiple vectors using the 
AutoLISP grvecs function. The following shows the syntax of the grvecs function: 


(grvecs vectors [trans_matrix]) 


Its arguments are as follows: 


vectors The vectors argument represents a list of the vectors that should be drawn and 
their colors. The formatting of each vector is (vec_color vec_from vec_to ...).The ACI 
value of the vec_color argument represents the vector’s color, and the vec_from and vec_to 


arguments represent the coordinate values to draw the vector. 


trans_matrix The trans_matrix argument represents the transformation matrix that 


should be applied to the coordinate values of the vectors being drawn. The trans_matrix 


argument is optional. For more information on transformation matrices, see Chapter 4, 
“Working with Lists.” 


The following is an example of drawing vectors in the drawing area with the grvecs func- 


tion. The results of the example are shown in Figure 5.8. 


; Draws rectangle that is 8x11 units in size with an ACI color of 6 
(grvecs '(6 (0 0) (8 0) 

6 (8 0) (8 11) 

6 (8 11) (0 11) 

6 (© 11) (0 0) 


nil 


FIGURE 5.8 
Drawing multiple 
vectors with the 
grvecs function 


TIP Changing the current view clears the temporary graphics, but you can use reactors in 
AutoCAD on Windows to redraw the vectors after a view change occurs. You'll learn about 
reactors in Chapter 12, “Working with ActiveX/COM Libraries (Windows only).” 
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NOTE If youare modifying an existing program that draws temporary vectors, you might need 
to use the grclear function to clear the display of the current viewport. The grclear func- 
tion is not needed in recent releases but might be required if you are using an earlier release. 


SETTING FOCUS TO THE GRAPHICS WINDOW (WINDOWS ONLY) 


Earlier releases of AutoCAD supported two different screens, two physical monitors: graphics 
and text. More recent releases use a modern user interface that has a graphics and a text 
window. The AutoLISP graphscr function collapses the history of the command-line window or 
hides the AutoCAD Text Window, which are expanded or shown with the textscr or textpage 
function. I discussed the textscr or textpage functions earlier in the “Expanding or Showing 
the Command-Line History” section. The graphscr function doesn’t accept any arguments. 


Conditionalizing and Branching Expressions 


The expressions that make up an AutoLISP program are executed sequentially; this is com- 
monly known as a linear program. In a linear program, execution starts with the first expression 
and continues until the last expression is executed. Although expressions are executed in a lin- 
ear order, AutoLISP programs can contain branches. Think of a branch as being no different than 
a fork in the road. 

Branches allow a program to make a choice as to which expressions should be executed next 
based on the results of a test condition. A test condition is an expression that evaluates to true 
or false; in AutoLISP, that would be T or nil, respectively. AutoLISP provides a wide range of 
operators and functions that can be used individually or with a logical grouping operator to see 
if more than one test condition evaluates to T or nil. The AutoLISP expressions if and cond are 
used to branch the expressions in your programs. 


Comparing Values 


As the complexity of a program grows, so does the need to use test conditions (that is, to perform 
conditional tests). Test conditions are used to compare values or settings in the AutoCAD envi- 
ronment against a known condition. AutoLISP operators and functions that are used to test con- 
ditions return T (if the condition being tested evaluates to true) or nil (if the condition evaluates 
to false). The AutoLISP operators and functions used to test a condition allow you to 


Compare two values for equality 
Determine if a value is numeric, zero, or negative 
Compare two values to see if one is greater than, less than, or equal to the other 


Check for a value being bound to a variable 


¢- ¢ è% è 


Check for a variable that contains a list 
This exercise shows how to work with some basic test conditions: 
1. At the AutoCAD Command prompt, type (setq num1 5 num2 3.5) and press Enter. 


2. Type (= num1 num2) and press Enter. 
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nil is returned as the two numbers are not equal to each other. 
3. Type (not (= num1 num2)) and press Enter. 


T is returned because the not function returns T if the argument it is passed is nil. 
Essentially it inverts the value it is passed; T becomes nil and nil becomes T. 


4. Type (= num1 (+ num2 1.5)) and press Enter. 


T is returned as the value assigned to num1 is equal to the value of the num2 variable and 
1.5 after they are added together. 


5. Type (<= num1 num2) and press Enter. 


nil is returned as the value assigned to the num1 variable is not less than or equal to the 
value assigned to the num2 variable. 


6. Type (<= num1 (+ num2 2.5)) and press Enter. 


T is returned as the value assigned to the num1 variable is less than or equal to the value 
assigned to the num2 variable. 


TESTING VALUES FOR EQUALITY 


Testing for equality is probably the most common test condition you will perform. For example, 
you might want to see if the user provided any input with one of the getxxxx functions that I 
mentioned in the “Requesting Input at the Command Prompt” section earlier or if the user just 
pressed Enter. In this case, you would be checking to see if the value returned by the function 
was equal to nil. The AutoLISP = (equal to) and /= (not equal to) operators are how values are 
commonly compared to each other. 

The following shows the syntax of the = and /= operators: 


(= atoml [atomN ...]) 
(/= atomi [atomN ...]) 


Here are the arguments: 


atom1 The atoml argument represents the atom you want to compare against the atoms 
represented by the atomN arguments. If all the atoms provided to the operator evaluate to the 
same value, T is returned; otherwise, nil is returned. 


atomN The atomN argument represents the second or any other values you want to compare. 


The following are examples of checking for equality with the = and /= operators, and the 
values that are returned: 


(= 1 1.0) 


(= 1 2) 
nil 


(/= 1 2) 
E 
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(/= nil (getpoint "\nSpecify point: ")) 
Specify point: Press Enter 
nil 


(/= nil (getpoint "\nSpecify point: ")) 
Specify point: Pick a point in the drawing area 
T 


(= 1 1.0 1) 
i 


(= 1 1.0 2) 
nil 


When comparing more than two atoms, the atoms are compared in pairs from left to right. 
For example, (= 1 1.0 1) is compared as (= 1 1.0) and (= 1.0 1). Since both pairings eval- 
uate to T, the = operator returns T. The expression (= 1 1.0 2) is evaluated as (= 1 1.0) and 
(= 1.0 2). Since both pairings don’t evaluate to T, the = operator returns nil. 

The AutoLISP eq and equal functions can be used to check a variable or the value of a vari- 
able for equality. The eq function checks to see if two variables point to the same location in 
memory and if the values are the same, whereas the equal function tests to see if two values are 
within a provided threshold or fuzzy factor. If the variables or values that are being tested with 
the eq and equal functions are equal, then T is returned; otherwise nil is returned. 

The following shows the syntax of the eq function: 


(eq varl var2) 


Here are the arguments: 


varli The varl argument represents the first variable you want to compare. The variable is 
defined with the setq function. 


Var2 The var2 argument represents the second variable to compare. The variable is defined 
with the setq function. 


The following shows the syntax of the equal function: 
(equal valuel value2 [fuzz_factor]) 


These are the arguments: 
valuel The valuel argument represents the first value you want to compare. 
value2 The value2 argument represents the second value you want to compare. 


fuzz_factor The fuzz_factor argument represents the tolerance or difference between 
the two compared values in order for the function to return T. If the two values are outside of 
the tolerance specified with the fuzz_factor argument, nil is returned. 
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The following are examples of checking for equality with the eq and equal functions, and 
the values that are returned: 


; vl is set to '(0 0 5), v2 is set to '(0 © 5), and v3 is set to variable v2 
(setq v1 '(0 © 5) v2 '(0 © 5) v3 v2) 
(0 © 5) 


(eq v1 v3) 
nil 


(eq v2 v3) 
T 


; Compares two values with a fuzz factor of 0.0625 
(equal 0.25 0.20 0.0625) 
T 


(equal 0.25 0.1875 0.0625) 
nil 


DETERMINING IF A VALUE IS GREATER OR LESS THAN ANOTHER 


The values that a user provides or the settings that define the AutoCAD environment aren’t 
always easily comparable for equality. Values such as the radius of a circle or the length of a 
line are often compared to see if a value is greater or less than another. The AutoLISP > (greater 
than) and < (less than) operators can be used to ensure that a value is—or isn't—greater than or 
less than another value. 

These two operators are great for limiting the value a user might enter with the getint, get- 
real, getdist, getangle, or getorient functions mentioned earlier, in the “Requesting Input at 
the Command Prompt” section. You can also use the > and < operators with looping expressions 
to count down or up, and to make sure that while incrementing or decrementing a value you 
don’t exceed a specific value. You might also use the > and < operators with a logical grouping 
operator to make sure a value is within a specific range of values. I discuss logical groupings in 
the “Grouping Comparisons” section later in this chapter. 

The > (greater than) operator returns T if the first number is greater than the second number; 
otherwise, nil is returned. The < (less than) operator returns T if the first number is less than 
the second number; otherwise, nil is returned. If the values being compared are equal, then nil 
is returned. The > and < functions can also be used with strings. When a string is provided, the 
sum of each character’s ASCII value is compared. 

The following shows the syntax of the > and < operators: 


(> valuel [valueN ...]) 
(< valuel [valueN ...]) 
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The arguments are as follows: 
valuel The valuel argument represents the first value you want to compare. 


valueN The valueN argument represents the two or more values you want to compare. 


The following are examples of comparing values with the > and < operators, and the values 
that are returned: 


(> 1 1.0) 
nil 


(> 2 1) 
T 


(> "ab" "ac") 
nil 


(> 132) 
nil 


(> 4 3 2) 
T 


(> 4 (getint "\nEnter a number less than 4: ")) 
Enter a number less than 4: 3 
T 


Enter a number less than 4: 4 
nil 


(< 1 1.0) 
nil 


(< 2 1) 
nil 


(< "ab" "ac") 
T 


(< 1 2 3) 
T 


(< 13 2) 
nil 


When comparing more than two values, the values are compared in pairs from left to right. 
For example, (< 1 2 3) iscompared as (< 1 2) and (< 2 3). Since both pairings evaluate to T, 
the < operator returns T. The expression (< 1 3 2) is evaluated as (< 1 3) and (< 3 2).Since 
both pairings don’t evaluate to T, the < operator returns nil. 
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In addition to comparing to see if a value is greater or less than another, you can check for 
equality. The >= (greater than or equal to) and <= (less than or equal to) operators allow you to 
check to see if a value is greater or less than another or if the two values are equal. The syntax 
and return values for the >= and <= operators are the same as the > and < operators, except T is 
returned if the values being compared are equal to each other. 

Here are examples of comparing values with the >= and <= operators, and the values that are 
returned: 


(>= 1 1.0) 
T 

(>= 1 2) 
nil 

(<= 1 1.0) 
T 

(<= 1 2) 
T 


TIP You can compare a value within a range of values by using logical groupings, which I cover 
in the “Grouping Comparisons” section later in this section. 


CHECKING FOR A VALUE OF NIL 


A value, variable, or expression can be checked to see if it evaluates to nil. The AutoLISP not 
function returns T if a value, variable, or expression normally returns nil. If nil is normally 
returned, T is returned instead. You can think of the not function as a way to invert the values T 
and nil. 

The following shows the syntax of the not function: 


(not atom) 


The atom argument represents the expression to evaluate, and then returns a value of T if 
atom evaluates to nil, or nil if atom evaluates to T. 
The following are examples of the not function and the values that are returned: 


(= 1 1.0) 
7 


(not (= 1 1.0)) 
nil 


(not (> 4 (getint "\nEnter a number less than 4: "))) 
Enter a number less than 4: 3 
nil 


Enter a number less than 4: 4 
T 
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Grouping Comparisons 
There are many times when one test condition is not enough to verify a value. One of the best 
examples of when you want to use more than one test condition is to see if a value is within a 
specific numeric range. Logical grouping operators are used to determine if the result of one or 
more test conditions evaluates to T. 

The AutoLISP and and or operators are the two logical grouping operators that can be used 
to test two or more test conditions. The and operator returns T if all the test conditions in a 
grouping return T; otherwise, nil is returned. The or operator returns T if at least one test con- 
dition in a grouping returns T; otherwise it returns nil. 

The following shows the syntax of the and and or operators: 


(and [test_conditionN ...]) 
(or [test_conditionNn ...]) 


The test_conditionN argument represents the test conditions that you want to group 
together and evaluate. 
The following shows examples of the and and or operators and the values that are returned: 


; Check to see if the number is between 1 and 5 

(setq num (getint "\nEnter a number between 1 and 5: ")) 
(and (>= 5 num) (<= 1 num) ) 

Enter a number between 1 and 5: 3 

T 


Enter a number between 1 and 5: 6 
nil 


; Checks to see if the value of the numl and num2 variables is a numeric value 
(setq num1 1.5 num2 "1.5") 

(or (= (type num1) 'REAL)(= (type numi) 'INT)) 

T 


(or (= (type num2) 'REAL)(= (type num2) 'INT)) 
nil 


Chapter 2 discussed the type function. 


Validating Values 


Prior to using a variable, you should test to see if the variable holds the type of value that you 
might expect. Although they do increase the complexity of a program, the additional expressions 
used to test variables are worth the effort as they help to protect your programs from unexpected 
values. Table 5.3 lists some of the functions that can be used to test the values of a variable. 
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TABLE 5.3: AutoLISP functions for testing the values of a variable 
FUNCTION DESCRIPTION 
boundp Checks to see if a symbol is bound to a variable; returns T or ni l. 
numberp Determines if a value is numeric; returns T or nil. 
minusp Checks to see if a numeric value is positive or negative; T is returned if the value is 
negative. 
zerop Determines if a value is 0 or not; returns T or ni l. 
Null Determines if a symbol is bound to the value of nil; returns T or nil. 


For more information on these and other validation functions, see the AutoCAD Help 
system. 


Evaluating if a Condition Is Met 


The AutoLISP operators and functions discussed in the previous sections allow a program to 
compare and test values to determine which expressions to execute by using a programming 
technique called branching. The most common branching method in most programming lan- 
guages is what is referred to as an If ... Then ... Else expression. In an If ... Then ... Else expres- 
sion, different sets of expressions are executed if the test condition is evaluated as true (or T) or 
false (or nil). 

In AutoLISP, the if function is used to define an If ... Then ... Else expression. The following 
shows the syntax of the if function: 


(if test_condition then_expression [else_expression]) 


The arguments are as follows: 


test_condition The test_condition argument represents the test condition that you want 
to evaluate and determine which expression to execute. If test_condition evaluates to T, the 
expression represented by then_expression is evaluated; otherwise, the expression repre- 
sented by else_expression is evaluated if provided. 


then_expression The then_expression argument represents the expression to evaluate if 
the test_condition argument evaluates to T. 


else_expression The else_expression argument represents the expression to evaluate if 
the test_condition argument evaluates to nil. The else_expression argument is optional. 


The following are examples of the if function: 


; Checks to see if the value entered is greater than 4 
(setq num (getint "\nEnter a number: ")) 
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(if (>= num 4) 
(prompt "\nNumber is 4 or greater") 
(prompt "\nNumber is less than 4") 
) 
Enter a number: 3 
Number is less than 4 nil 


Enter a number: 5 
Number is 4 or greater nil 


; Checks to see if the user specified a point 

(if (setq pt (getpoint "\nSpecify a point: ")) 
(prompt (strcat "\nUser specified a point of: " (vl-princ-to-string pt))) 
(prompt "\nNo point specified") 

) 

Specify a point: Press Enter without specifying a point 

No point selectednil 


Specify a point: Pick a point in the drawing area 
User specified a point of: (15.0089 11.0815 0.0)nil 


Without any extra help, the AutoLISP if function can only accept a single expression for the 
then_expression or else_expression argument. If you pass more than two expressions to 
the if function and try to execute your program, AutoLISP replies with the message ; error: 
syntax error. 


(if (setq pt (getpoint "\nSpecify a point: ")) 
(prompt (strcat "\nUser specified a point of: " (vl-princ-to-string pt))) 
(command ". circle" pt 2) 
(prompt "\nNo point specified") 

) 


3 error: syntax error 


It isn’t uncommon that you will want to execute more than one expression based on the value 
returned by the test condition of the if function. When you want to use more than one expres- 
sion, use the progn function to group more than one expression into a single expression. The 
syntax of the if expression is as follows: 


(if test_condition 
(progn 
then_expressions 
) 
(progn 
else_expressions 
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NOTE Youneed to use the progn function only when more than one expression is being passed 
to the then_expression or else_expression argument of the if function. You can use the 
progn function, though, when only one expression is being used. 


The following is an example of the if and progn functions that are used to draw a circle only 
after a valid point is specified: 


; Prompts for a point and then draws a circle and 
; sets its color to ACI 3 if a point was specified. 
(if (setq pt (getpoint "\nSpecify center point: ")) 


(progn 

(command ". circle" pt 2) 

(command ",_change" (entlast) wee wip" Wig" "3" my 
) 


) 


The following is an example of nested if and progn functions that allow the user to draw a 
circle or hexagon based on the keyword provided: 


; Prompts for a keyword, and then draws either a circle or hexagon 

; on different layers based on a specified center point. 

(initget "Circle Hexagon") 

(if (setq kword (getkword "\nEnter object to create [Circle/Hexagon]: ")) 
(if (= kword "Circle") 


(progn 
(command M layer" " m" "Circles" " c" "30" "n ww) 
(command "._ circle" PAUSE 1.5) 
) 
(progn 
(command Wy layer" " m" "Hexagons" " c" "150" wee my 
(command ". polygon" "6" PAUSE "_i" 1.65) 
) 
) 
(prompt "\nNo option specified.") 


Testing Multiple Conditions 
The if function allows for programs to execute one of two possible sets of expressions based on 
the results of a single test condition. However, there are times when multiple test conditions are 
needed to interpret a value or user input. Although it is possible to use multiple if expressions 
to evaluate more than one test condition, the AutoLISP programming language contains the 
cond function, which allows for the evaluation of more than one test condition. 

The test conditions of the cond function are evaluated one at a time in a top-down order. 
When evaluation of the cond function begins, the first test condition is evaluated; if it returns 
true (T), the expressions associated with it are evaluated and the evaluation of the cond function 
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ends. If the first test condition doesn’t return true (T), the next test condition is evaluated and 
so on until all test conditions have been evaluated or one test condition returned true (T) before 
reaching the last test condition. Optionally, a set of expressions can be executed if none of the 
other test conditions of the cond function evaluate to true (T). 

The following shows the syntax of the cond function: 


(cond 
[(test_conditionN then_expressionN) 


[ (else_expressionN) ] ] 


) 


Its arguments are as follows: 


test_conditionN The test_conditionN argument represents the test condition to be eval- 
uated. If test_conditionN evaluates to T, the expressions represented by then_expressionN 
are executed. 


then_expressionN The then_expressionN argument represents the expressions to evalu- 
ate if the test_conditionN argument evaluates to T. 


else_expressionN The else_expressionN argument represents the expressions to evaluate 
if none of the test conditions represented by the test_conditi7onN argument evaluates to T. 
The else_expressionN argument is optional. 


The following are examples of the cond function: 


; Gets the current value of the IMAGEFRAME system variable 

; and returns a textual description of that value. 

(setq cur_imgfrm (getvar "imageframe") ) 

(cond 
((= cur_imgfrm 0) (prompt "\nImage frame not displayed or plotted.")) 
((= cur_imgfrm 1)(prompt "\nImage frame displayed or plotted.") ) 
((= cur_imgfrm 2) (prompt "\nImage frame not plotted.") ) 


; Prompts the user for a keyword and if they press Enter 
; without a value the nil value should be interpreted as Blue. 
(initget "Blue Green Red") 
(setq kword (getkword "\nEnter color option [Blue/Green/Red] <Blue>: ")) 
(cond 

((or (= kword nil) (= kword "Blue")) (prompt "\nSelected Blue") ) 

((= kword "Red" ) (prompt "\nSelected Red") ) 

((= kword "Green") (prompt '"\nSelected Green") ) 
) 
Enter color option [Blue/Green/Red] <Blue>: Press Enter without a value 
Selected Blue 


Enter color option [Blue/Green/Red] <Blue>: g 
Selected Green 
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; Prompts the user for a keyword or a numeric value 
(initget "A B C") 
(setq num (getreal "\nEnter a number or [A/B/C]: ")) 
(cond 
((and (= (type num) 'REAL)(> num ©))(prompt "\nGreater than 0") ) 
((and (= (type num) 'REAL)(= num ©)) (prompt "\nValue is 0")) 
((and (= (type num) 'REAL)(< num ©))(prompt "\nLess than 0")) 
((and (= (type num) 'REAL)(> num ©))(prompt "\nGreater than 0") ) 
((= num nil) (prompt "\nNo value or option provided") ) 
(T 
(prompt "\nAn option was selected. ") 
(prompt (strcat "\nOption chosen: " (vl-princ-to-string num) )) 


) 
Enter a number or [A/B/C]: 1 
Greater than 0 


Enter a number or [A/B/C]: B 
An option was selected. 
Option chosen: B 


Enter a number or [A/B/C]: Press Enter without a value 
No value or option provided 


Repeating and Looping Expressions 


Early in my career as a drafter, I learned one key fact about myself: I don’t handle repetition 
well at all. This discovery is what led me to AutoCAD customization and eventually AutoLISP 
programming. AutoLISP—and most programming languages, for that matter—have no problem 
with repetition, as they support a concept known as loops. Loops allow for a set of expressions to 
be executed either a finite number of times or infinitely while a condition is met. 

The AutoLISP programming language contains four functions that can be used to repeat or 
loop a set of expressions, or even iterate through the items of a list or collection object. Table 5.4 
describes these functions. 


TABLE 5.4: AutoLISP looping functions 
FUNCTION DESCRIPTION 
repeat Executes a set of expressions a finite number of times. For more information, see the 


next section. 


while Executes a set of expressions as long as a test condition returns T. For more informa- 
tion, see the “Performing a Task While a Condition Is Met” section. 
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TABLE 5.4: AutoLISP looping functions (CONTINUED) 
FUNCTION DESCRIPTION 
foreach Iterates through a list and assigns each element to a variable one at a time, and the 
variables can then be used by a set of expressions. I discussed the foreach function 
in Chapter 4. 
vlax-for Iterates through a collection object and assigns each object to a variable one at a 


time, and the variables can then be used by a set of expressions. Chapter 12 dis- 
cusses the v lax- for function. 


Repeating Expressions a Set Number of Times 

The easiest way to loop through a set of expressions in AutoLISP is to use the repeat function. 
The first argument of the repeat function determines the number of times you want to loop 
through the set of AutoLISP expressions. Looping through a set of expressions a known number 
of times is a great way to iterate the objects of a selection set or to prompt the user a finite num- 
ber of times. The repeat function returns the value of the last expression in the loop. 


TIP When working with a large number of loops, consider keeping track of the current loop that 
is being executed by incrementing the value of a user-defined variable. Then, at a set interval, 
let the user know that something is still happening so they know that AutoCAD hasn't stopped 
responding. 


The following shows the syntax of the repeat function: 
(repeat loop_count [expressionN]) 


Its arguments are as follows: 


loop_count The loop_count argument represents the number of times you want to loop 
through the expressions specified by the expressionN argument. 


expressionN The expressionN argument represents the expressions that should be exe- 
cuted each time the loop is started. 


The following are examples of the repeat function: 


; Loops the expressions 5 times, the variable 
; cnt is incremented by 1 with each loop 
(setq cnt 0) 
(repeat 5 

(terpri) 

(princ (setq cnt (1+ cnt))) 

(princ) 


afi UNES 
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; Loop restricts the user to specifying three 
3; points to draw a closed object 
(defun c:3SF ( / old_cmdecho) 

(setq old_cmdecho (getvar "cmdecho") ) 

(setvar "cmdecho" 0) 


(command "._line") 
(repeat 3 

(command (getpoint "\nSpecify a point: ")) 
) 


(command "_c") 
(setvar "cmdecho" old_cmdecho) 
(princ) 

) 

C:3SF 

Specify a point: 

Specify a point: 

Specify a point: 


Performing a Task While a Condition Is Met 
The repeat function, as I mentioned in the previous section, can be used to execute a set of 
expressions a finite number of times. However, it isn’t always easy to know just how many times 
a set of expressions might need to be executed to get the desired results. When you are unsure 
of the number of times a set of expressions might need to be executed, you can use the while 
function. The whi le function uses a test condition, just like the if and cond functions, to deter- 
mine whether the set of expressions should be executed. The set of expressions is executed as 
long as the test condition returns T. The test conditions that can be used are the same ones that I 
mentioned earlier in the “Comparing Values” and “Grouping Comparisons” sections. The while 
function returns the value of the last expression in the loop. 

The following shows the syntax of the while function: 


(while test_condition [expressionN]) 


Its arguments are as follows: 


test_condition The test_condition argument represents the expression that should be 
used to determine if the expressions represented by the expressi7onN argument should be 
executed. If test_condition evaluates to T, one loop occurs and then test_condition is 
evaluated again. Looping continues as long as test_condition evaluates to T. 


expressionN The expressionN argument represents the expressions that should be exe- 
cuted each time the loop is started. 


The following are examples of the while function: 


; Loops the expressions 5 times, the variable 


133 


134 |CHAPTERS5 REQUESTING INPUT AND USING CONDITIONAL AND LOOPING EXPRESSIONS 


3 cnt is decremented by 1 with each loop 
(setq cnt 5) 
(while (> cnt 0) 
(terpri) 
(princ (setq cnt (1- cnt))) 
(princ) 


OrFRPFNW KRY 


; Loop continues prompting for points until 
; the user presses Esc or Enter 
(defun c:C25 ( / old_cmdecho) 
(setq old_cmdecho (getvar "cmdecho") ) 
(setvar "cmdecho" 0) 


(prompt "\nSpecify center point or <enter> to exit: ") 
(while (setq pt (getpoint) ) 
(command "._ circle" pt 0.25) 


(setvar "cmdecho" old_cmdecho) 
(princ) 

) 

C:C25 

Specify center point: 


; Custom function prompts the user for a number between 1 and 5. 
; If the user enters an incorrect value, it prompts the user again, or 
; ends if the user presses Enter 
(defun c:NumberRange ( / askForNumber msg num) 
(setq askForNumber '(getint "\nEnter a number between 1 and 5: ")) 
(setq msg '(prompt (strcat "\nUser Entered: " (itoa num) ))) 


(setq num (eval askForNumber) ) 


(if (/= num nil) 
(progn 
(while (and (/= num nil) 
(not (and (>= 5 num) (<= 1 num))) 
) 
(prompt "\nTry again. Number must be between 1 and 5."') 
(setq num (eval askForNumber) ) 
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(if (/= num nil) (eval msg) ) 
(princ) 
) 


Enter a number between 1 and 5: 0 


Try again. Number must be between 1 and 5. 
Enter a number between 1 and 5: 6 


Try again. Number must be between 1 and 5. 
Enter a number between 1 and 5: 3 


User Entered: 3 


Listing 5.3 shows a set of custom functions that display an animated progress message in 
the status bar area. The custom functions can be helpful when processing a large number of 
objects or when writing/reading values to/from an external file. Instead of using the princ 
function, the grtext function is used to display the text whereas the vl-string-subst function 
is used to give the appearance of an animated progress message by replacing one character with 
another before redisplaying the new message. 

Figure 5.9 shows what the progress bar looks like. Underscores are changed to equal 
symbols in the first pass and then the equals symbols are changed to underscores in the next. 
Once the functions are all loaded, start the progress-test function by entering it at the 
Command prompt to see it in action. 


LISTING 5.3: Animated progress message in the status bar (Windows only) 


; Initializes the variables and the status bar 
; Usage: (progress-start) 
(defun progress-start ( / ) 

(setq *global-progress-value* nil 
*global-progress-increment*® nil 
*global-progress-replace* nil) 

(grtext -1 "") 

(princ) 


) 


(defun progress (prefixText / temp) 
(setq increment 10) 


; Check to see if the global variable is initialized 
(if (= *global-progress-value* nil) 
(progn 
(setq *global-progress-value* prefixText 
*global-progress-increment* 0 
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*global-progress-replace* (list mm Wa") ) 
(repeat 10 
(setq *global-progress-value* (strcat *global-progress-value* "=")) 


) 


; Pause for 1/20 of a second to allow 
; AutoCAD time to paint the application window 
(command "._delay" 50) 


; Setup replacement character order 
(if (> *global-progress-increment* increment) 
(progn 
(setq *global-progress-replace* (reverse *global-progress-replace* ) 
*global-progress-increment* 0) 


) 


; Display custom message in the status bar 
(grtext -1 (setq *global-progress-value* 
(vl-string-subst (nth 0 *global-progress-replace*) 
(nth 1 *global-progress-replace*) 
*global-progress-value™*) ) ) 
(setq *global-progress-increment* (1+ *global-progress-increment*) ) 


(princ) 


) 


; Clear the global variable and the value posted to the status bar 
; Usage: (progress-end) 
(defun progress-end ( / ) 
(setq *global-progress-value* nil 
*elobal-progress-increment*® nil 
*elobal-progress-replace* nil) 
(grtext -1 "") 
(princ) 


) 


(defun c:progress-test ( / count) 
(setvar "cmdecho" 0) 
(setq count 50) 


(progress-start) 


(while (> (setq count (1- count)) 0) 


EXERCISE: GETTING INPUT FROM THE USER TO DRAW THE PLATE 


(progress "Working: ") 
(princ) 


) 


(progress-end) 
(setvar "cmdecho" 1) 
(princ) 


) 


FIGURE 5.9 x 


Custom animated 


progress message 14| 41> [bi Model ¿ Layout! Z Layout2 / 


Progress message 


Exercise: Getting Input from the User to Draw the Plate 


In this section, you will continue to build on the drawplate function that was originally intro- 
duced in Chapter 2. The key concepts I cover in this exercise are as follows: 


Requesting Input Input functions can be used to get values from the user at the Command 
prompt. 

Creating New Point Lists Values from different point lists can be used to create new coor- 
dinate values. 


Using Conditional Statements Conditional statements are a great way to check the data 
provided by a user. 


Looping Until a Condition Is Met Loops allow you to execute a set of expressions a spe- 
cific number of times or while a condition remains true (T). You can use a loop to keep allow- 
ing the user to provide input. 


NOTE Thestepsin this exercise depend on the completion of the steps in the “Exercise: Adding 
Holes to the Plate” section of Chapter 4. If you didn’t complete the steps, do so now or start 
with the ch0O5_drawplate.lsp and chO5_utility.lsp sample files available for download 
from www. sybex.com/go/autocadcustomization. The sample files should be placed in the 
MyCustomF 7 les folder within the Documents (or My Documents) folder, or the location where 
you are storing the LSP files. Also, remove the ch05_ from the name of each file to match the 
filenames used in the steps. 


Revising the drawplate Function 


The changes to the drawplate function implement the use of user input to get points and dis- 
tances, which are then used to draw the plate at various sizes and locations in the drawing. 
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The following steps explain how to update the drawplate. lsp file with the revised drawplate 
function: 


1. Open the drawplate. lsp file by doing one of the following: 


@ On Windows, browse to and double-click the drawplate.1sp file to open it in 
Notepad. If the file doesn’t open, start Notepad and click File > Open. From the Files 
Of Type drop-down list, select All Files (**). Then browse to and select the draw- 
plate. lsp file, and then click Open. 


@ On Mac OS, browse to and double-click the drawplate.1sp file to open it in TextEdit. 
If the file doesn’t open, start TextEdit and click File > Open. Browse to and select the 
drawplate. lsp file, and then click Open. 


2. In the text editor area, locate the drawplate function and insert the following code snip- 
pet (or modify the text in the file to match what is formatted in bold): 


5; Draws a rectangular plate 
(defun c:drawplate ( / ptl pt2 pt3 pt4 width height basePt insPt textValue) 


; Create the layer named Plate or set it current 
(createlayer "Plate" 5) 


3; Define the width and height for the plate 
(if (= *drawplate_width* nil) (setq *drawplate_width* 5.0)) 
(if (= *drawplate_height* nil) (setq *drawplate_height* 2.75) ) 


3 Get recently used values from the global variables 
(setq width *drawplate_width*) 
(setq height *drawplate_height*) 


5; Prompt the current values 
(prompt (strcat "\nCurrent width: " 
(rtos *drawplate_width* 2) 
" Current height: " 
(rtos *drawplate_height* 2))) 


3; Set up default keywords 
(initget "Width Height") 


3; Continue to ask for input until a point is provided 
(while (/= (type 
(setq basePt 
(getpoint "\nSpecify base point for plate or [Width/Height]: ")) 
) 
"LIST 
) 
(cond 
3; Prompt for the width of the plate 
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((= basePt "Width"') 


(setq width (getdist (strcat "\nSpecify the width of the plate <" 

(rtos *drawplate_width* 2) ">: "))) 
3; If nil is returned, use the previous value from the global variable 
(if (/= width nil) (setq *drawplate_width* width) ) 


3; Prompt for the height of the plate 
((= basePt "Height") 
(setq height (getdist (strcat "\nSpecify the height of the plate <" 
(rtos *drawplate_height* 2) ">: "))) 
3; If nil is returned, use the previous value from the global variable 
(if (/= height nil)(setq *drawplate_height* height) ) 


3; Set up default keywords again 
(initget "Width Height") 


3 Set the coordinates to draw the rectangle 
(setq pt1 basePt 
3| lower-left corner |; 
pt2 (list (+ (car basePt) width) (cadr basePt) 0) 
3| lower-right corner |; 
pt3 (list (+ (car basePt) width) (+ (cadr basePt) height) 0) 
;| upper-right corner |; 
pt4 (list (car basePt) (+ (cadr basePt) height) 0) 
;| upper-left corner |; 


; Draw the rectangle 
(createrectangle pt1 pt2 pt3 pt4) 


; Create the layer named Holes or set it as current 
(createlayer "Holes" 1) 


; Draw the first circle 
(createcircle (polar pt1 (/ PI 4) 0.7071) 0.1875) 


; Array the circle to create the other bolt holes 
(command "._-array" (entlast) "" "_r" 2 2 (- height 1) (- width 1)) 


; Set the insertion point for the text label 
(setq insPt (getpoint "\nSpecify label insertion point: ")) 
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; Define the label to add 

(setq textValue (strcat "PLATE SIZE: " 
(vl-string-right-trim " .0" (rtos width 2 2)) 
Wy 
(vl-string-right-trim " .0" (rtos height 2 2)) 


; Create label 
(createlayer "Label" 7) 
(createtext insPt "_c" 0.5 0.0 textValue) 


3; Save previous values to global variables 
(setq *drawplate_width* width) 
(setq *drawplate_height* height) 


3; Exit "quietly" 
(princ) 


) 


3. Click File > Save. 


Using the Revised drawplate Function 


Now that that the drawplate. lsp file has been revised, you must load the file into AutoCAD 
along with the utility. lsp file before you can use the changes made. 

The following steps explain how to load the LSP files into AutoCAD and then start the draw- 
plate function: 


1. Do one of the following: 


D @ On the ribbon, click the Manage tab > Customization panel > Load Application 
“4 (Windows). 


@ On the menu bar, click Tools > Load Application (Mac OS). 
@ At the Command prompt, type appload and press Enter (Windows and Mac OS). 


2. When the Load/Unload Applications dialog box opens, browse to the MyCustomF7 les 
folder and select the drawplate. lsp file. 


3. Press and hold the Ctrl key on Windows or the Command key on Mac OS, and select the 
utility. lsp file. Click Load. 


4. If the File Loading - Security Concerns message box is displayed, click Load. 
5. Click Close to return to the drawing area. 


6. At the Command prompt, type drawplate and press Enter. 
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7. Press F2 on Windows or Fn-F2 on Mac OS to expand the command-line window. The cur- 
rent width and height values for the plate are displayed in the command-line history. 
Current width: 5.0000 Current height: 2.7500 


8. Atthe Specify base point for the plate or [Width/Height]: prompt, type wand 
press Enter. 


9. Atthe Specify the width of the plate <5.0000>: prompt, type 3 and press Enter. 


10. Atthe Specify base point for the plate or [Width/Height]: prompt, type hand 
press Enter. 


11. Atthe Specify the height of the plate <2.7500>: prompt, type 4 and press Enter. 


12. Atthe Specify base point for the plate or [Width/Height]: prompt, pick a point 
in the drawing area to draw the plate and holes based on the width and height values 
specified. 


13. Atthe Specify label insertion point: prompt, pick a point in the drawing area 
below the plate to place the text label. 


14. Type zoom and press Enter, and then type e and press Enter. 


Figure 5.10 shows a number of different plates that were drawn at different sizes with the 
drawplate function. 


FIGURE 5.10 o Ọ 
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15. Execute the drawplate function again, and pick a point in the drawing without changing 
the current width and height values. The plate should be drawn using the previous value. 


16. Continue trying the drawplate function with different input values. 


FÀ 


Chapter 6 


Creating and Modifying Graphical 
Objects 


The AutoLISP® programming language is great for creating and modifying objects. There are 
two types of objects that you can create or modify: graphical and nongraphical. Graphical 
objects are those that you can see and interact with in the drawing area, whether in model or 
paper space. Nongraphical objects are those that you don’t create in the drawing area but that 
can affect the appearance of graphical objects. I discuss working with nongraphical objects in 
Chapter 7, “Creating and Modifying Nongraphical Objects.” 

The command function is the most common method that AutoLISP programmers use to cre- 
ate and modify objects, but it isn’t the most efficient when you are trying to modify individual 
properties of an object. Even creating lots of objects in the Autodesk® AutoCAD® program can 
be slower with the command function. Along with the command function, objects can be created 
and modified directly by setting property values as part of an entity data list. Extended data 
(XData) can also be attached to an object as a way to differentiate one object from another or, in 
some cases, to affect the way an object might look in the drawing area. 


Working with Entity Names and Dotted Pairs 


Creating and modifying objects with AutoLISP requires the understanding of two concepts: 
entity names and entity data. Entity names, also known as enames, are numeric values that are 
assigned to graphical and nongraphical objects stored in a drawing. An ename is expressed as 
the ENAME data type in AutoLISP. When you want to access an object, you use an ename. After 
an ename has been obtained, you can then access the object’s properties through its entity data 
list. An entity data list is a list that contains information about an object. In addition to modify- 
ing an object using an entity data list, you can create objects with entity data lists. I discuss how 
to create an object with an entity data list in the “Adding Objects to a Drawing” section, and 
how to get an ename for an object and the entity data list in the “Modifying Objects” section. 


a Real World Scenario 


RECOVERING FROM A DAYDREAM 


It is Monday morning and you just got back from vacation. For the most part, you are still thinking 
about the great time you had with the family at the beach. Before you realize it, you have placed all 
your dimensions and hatch objects on an incorrect layer. Never fear—AutoLISP to the rescue. Using 
a few lines of AutoLISP code, you select the misplaced objects and move them onto the correct layer. 
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Each entity data list is made up of many smaller lists that describe the properties of an object. 
The smaller lists are value pairings commonly known as dotted pairs. They are called dotted 
pairs because a dot usually separates the key element from the value of the list. The key element 
is commonly a DXF group code (which is of the integer data type) and used to let AutoCAD 
know the type of data for the value in the dotted pair. Some DXF group codes have common 
uses, whereas others have a more general meaning. I discuss some DXF group codes during this 
chapter, but you will need to refer to the AutoCAD Help system for a listing of all supported 
DXF group codes by object. 

The value of a dotted pair can be made up of more than one item. When a value contains 
more than one item, no dot is provided, as is the case with coordinate values. Here is an example 
of an entity data list for a circle: 


((-1 . <Entity name: 7ff79b005dc0>) (© . "CIRCLE") 

(330 . <Entity name: 7ff79b0039fO>) (5 . "1D4") (100 . "AcDbEntity") 
(67 . 0) (410 . "Model") (8 . "0") (100 . "AcDbCircle") 

(10 0.0 0.0 0.0) (40 . 0.875) (210 0.0 0.0 1.0)) 


The DXF group codes 10 and 40 are used to describe the circle. The DXF group code 10 represents 
the center point of the circle (10 0.0 0.0 0.0), whereas the DXF group code 40 represents the 
radius of the circle, which is set to a value of 0.875. Even though you can use the circle com- 
mand to create a circle based on a diameter value, AutoCAD stores only the circle’s radius as part 
of the drawing. 

DXF group codes don’t always have the same meaning. For example, the DXF group code 10 
is used by both lines and circles, but for line objects the code represents the line’s starting point, 
as shown in the following entity data list: 


((-1 . <Entity name: 7ff79b005e00>) (© . "LINE") 

(330 . <Entity name: 7ff79b0039f0>) (5 . "1D8") (100 . "AcDbEntity") 
(67 . 0) (410 . "Model") (8 . "0") (100 . "AcDbLine") 

(10 0.0 5.0 0.0) (11 5.0 5.0 0.0) (210 0.0 0.0 1.0)) 


Table 6.1 lists some of the most common DXF group codes that are used by objects in a draw- 
ing. For additional information on DXF group codes, search on “DXF entities section” in the 
AutoCAD Help system. 


TABLE 6.1: Common DXF group codes 


DXF GROUP CoDE DESCRIPTION 


0 Specifies the object’s type 

6 Specifies the linetype that an object is assigned; not used if the linetype is 
assigned by layer 

8 Specifies the layer on which an object is placed 

10 Specifies the start, center, elevation, or insertion point for many different objects 


11 Specifies the endpoint or direction vector for many different objects 
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TABLE 6.1: Common DXF group codes (CONTINUED) 


DXF GROUP CODE DESCRIPTION 


40 Specifies the radius for circles, height for text, and ratio between the major and 
minor axis of an ellipse 


62 Specifies the color that an object is assigned; not used if the color is assigned by 
layer 


REFERENCING OBJECTS USING HANDLES 


Enames aren't the only way you can reference an object in a drawing. When a drawing is closed and 
reopened, a new ename is assigned to each object in the drawing. However, each object created in 
a drawing is assigned a unique string value called a handle. 


A handle is a hexadecimal number value that is unique for each object in a drawing and can be 
used to reference an object when the drawing is closed and reopened. While the same handle can 
be used in more than one drawing, the handle remains unique and unchanged for an object in a 
drawing. The handle of an object can be accessed from an object’s entity data list; the dotted pair 
with the DXF group code 5 contains the object’s handle. 


Handles are commonly used to export information about the objects in a drawing and process the infor- 
mation externally before using the information to update the objects in the drawing. The AutoLISP 
handent function accepts a string value that represents an object’s handle in the drawing and returns 
the object’s current ename. 


The following shows the syntax of the handent function: 
(handent handle) 
The handle argument represents an object’s handle and must be expressed as a string. 


You can get an object’s handle using the list command or the AutoLISP entget function, which 
I discuss later, in the “Modifying Objects” section. The following is an example that gets the entity 
name of the Block symbol table (or a different object in your drawings)—which has a handle of 
"1"—with the handent function: 


(handent "1") 
<Entity name: 7ff79b003810> 


Creating a Dotted Pair 
A dotted pair is a list that is created using the AutoLISP cons or quote (') function. When creat- 
ing a dotted pair, you need to know two things: the key element and the value to be associated 
with the key element. Although the key element can be of any data type with the exception of 
a list, it is commonly either a string or integer. In entity data lists, the key element is an integer 
value that represents a DXF group code. 

The following shows the syntax of the cons function: 


(cons key atom) 
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The arguments are as follows: 
key The key argument represents the index or unique identifier for the dotted pair. 


atom The atomargument represents the value that you want to associate with the index or 
unique identifier specified by the key argument. 


The following examples show how to create dotted pairs with the cons function, and the 
values that are returned: 


; Dotted pair with a system variable name as the key and its value 
(cons "cmdecho" 0) 
("cmdecho" . 0) 


; DXF group code 10 with a coordinate value of 0.5,5.5,0 
(cons 10 (list 0.5 5.5 0.0)) 
(10 0.5 5.5 0.0) 


; DXF group code 40 with a value of 0.875 
(cons 40 0.875) 
(40 . 0.875) 


You can also use the quote function to create a dotted pair. The following examples show 
how to create dotted pairs with the quote function, and the values that are returned: 


; Dotted pair with a system variable name as the key and its value 
"("cmdecho" . 0) 
("cmdecho" . 0) 


; DXF group code 10 with a coordinate value of 0.5,5.5,0 
"(10 0.5 5.5 0.0) 
(10 0.5 5.5 0.0) 


; DXF group code 40 with a value of 0.875 
'(40 . 0.875) 
(40 . 0.875) 


Accessing the Elements of an Entity Data List and Dotted Pair 


Accessing the elements of an entity data list and a dotted pair is like accessing the elements 
of a regular list. Although you can use many of the list-related functions that I discussed in 
Chapter 4, “Working with Lists,” the AutoLISP assoc function is one of the functions that is 
frequently used when working with an entity data list. The assoc function is used to return a 
dotted pair with a specific key element in an entity data list. 

The following shows the syntax of the assoc function: 


(assoc key edlist) 
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The arguments are as follows: 


key The key argument represents the key (left) element of a dotted pair and is used as a way 
to locate a dotted pair within the list specified by the edlist argument. This argument can be 
a string or integer value. 


edlist The edlist argument represents the list in which you want to look for a dotted 
pair that contains the key argument as the key element. The first matching dotted pair is 
returned. 


Here is an example that shows how to return the first dotted pair in the entity data list that 
has a key (left) element of 40: 


; Returns the entity data list of the last object 

; added to the drawing, which is a circle in this example 

(setq ed (entget (entlast) )) 

((-1 . <Entity name: 7ff773005dc0>) (© . "CIRCLE") 
(330 . <Entity name: 7ff7730039f0>) (5 . "1D4") (100 . "AcDbEntity") 
(67 . 0) (410 . "Model") (8 . "0") (100 . "AcDbCircle") 
(10 5.0 6.5 0.0) (40 . 2.0) (210 0.0 0.0 1.0)) 


; Returns the dotted pair with the key element of 40 in the entity data list 
(assoc 40 ed) 
(40 . 2.0) 


I explain the entlast and entget functions in the “Selecting an Individual Object” and 
“Updating an Object’s Properties with an Entity Data List” sections later in this chapter. 

The AutoLISP car and cdr functions can also be helpful when working with dotted pairs. 
The car function returns the key element of a dotted pair and the cdr function returns the 
value. 


; Returns the key element of the dotted pair 
(car (assoc 40 ed)) 
40 


; Returns the value of the dotted pair 
(cdr (assoc 40 ed)) 
2.0 


Adding Objects to a Drawing 


Adding objects to a drawing can be done using standard AutoCAD commands with the command 
or entmake function. The entmake function accepts an entity data list that defines an object to be 
added to the drawing. All of the properties required to create an object must be contained in the 
entity data list; otherwise, the object won't be created. The properties required by the object are 
documented as part of the DXF Reference documentation in the AutoCAD Help system, but you 
might need to perform some trial and error to develop the proper entity data list that creates a 
new object. 


148 | CHAPTER6 CREATING AND MODIFYING GRAPHICAL OBJECTS 


(©) Real World Scenario 


GOING FURTHER WITHOUT COMMANDS 


Do you find yourself avoiding tables even though your boss likes the look they provide in draw- 
ings? Do you wish tables were more efficient for the type of information you add to them? You're 
not alone. Most objects can be created and modified using commands at the Command prompt, 
but tables unfortunately are not among them. AutoLISP can help you out. The AutoCAD table 
command provides limited functionality to create a table, but it can’t be used to populate or modify 
a table. Using AutoLISP, you can create a table using the entmake function while modifying and 
populating the table with the entget and entmod functions. Once again, with AutoLISP you have 
reclaimed part of your day for other tasks, such as working on additional projects or freeing up 
time to learn more about AutoLISP. 


For some objects it’s easier to determine which properties are required; for example, a circle 
requires a center point and radius whereas a line requires a start and endpoint. The best way 
to figure out which properties are required when creating an object is to create a new object in 
a drawing of the type you want to create with the entmake function. Once the object is created, 
enter the following code at the AutoCAD Command prompt to see the entity data list associated 
with the object: 


(entget (entlast)) 


For example, if you drew a circle with a center point of 5,6.5,0 and a radius of 2.0, the entity 
data list that is returned might look like this: 


((-1 . <Entity name: 7ff773005dc0>) (© . "CIRCLE") 

(330 . <Entity name: 7ff7730039f0>) (5 . "1D4") (100 . "AcDbEntity") 
(67 . 0) (410 . "Model") (8 . "0") (100 . "AcDbCircle") 

(10 5.0 6.5 0.0) (40 . 2.0) (210 0.0 0.0 1.0)) 


In the previous example, the DXF group codes -1, 5, and 330 were automatically generated 
and assigned to the object. Those DXF group codes shouldn't be part of the entity data list 
when you create a new object with the entmake function. Table 6.2 describes the DXF group 
codes -1, 5, and 330. 


TABLE 6.2: Automatically generated DXF group code values 


DXF GROUP CODE DESCRIPTION 


-1 Ename assigned to the object while the drawing is open in memory; the value 
changes each time the drawing is opened. 


5 Unique handle that is assigned to the object; it’s a string value. 


330 Pointer to the owner of the object. 
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After removing the DXF group codes that are automatically generated, the entity data list 
looks a bit less cluttered and easier to understand: 


((O . "CIRCLE") (100 . "AcDbEntity") (67 . 0) (410 . "Model") (8 . "ọ") 
(100 . "AcDbCircle") (10 5.0 6.5 0.0) (40 . 2.0) (210 0.0 0.0 1.0)) 


The DXF group codes 67, 410, 8, and 210 are optional; if they aren’t provided as part of the 
entity data list, AutoCAD uses the current settings and context of the drawing to populate 
the values of the properties they represent. Table 6.3 describes the DXF group codes 67, 410, 
8, and 210. 


TABLE 6.3: Optional DXF group code values 


DXF GROUP CODE DESCRIPTION 


67 Indicates that the object is in model space (0) or paper space (1) 
410 Named layout tab that the object exists on 

8 Layer in which the object is placed 

210 Extrusion direction of the object 


After removing the DXF group codes that are optional, the entity data list becomes even 
easier to understand: 


((0 . "CIRCLE") (100 . "AcDbEntity") (100 . "AcDbCircle") 
(10 5.0 6.5 0.0) (40 . 2.0)) 


The entity data list that now remains with the DXF group codes 0, 100, 10, and 40 represents 
the entity data needed to create a new circle with the entmake function. For additional informa- 
tion on DXF group code values, search on “DXF entities section” in the AutoCAD Help system. 
Table 6.4 describes the DXF group codes 0, 100, 10, and 40. 


TABLE 6.4: Required DXF group code values 
DXF GROUP CODE DESCRIPTION 
0 Entity type. 


100 Sub/entity class that the object is based on. Not all objects require these values. If 
the object doesn’t get created without them, add them to the entity data list and the 
object should be created. 


10 Center point of the circle. 


40 Radius of the circle. 
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Once you have the entity data list that describes the object you want to create, it can then be 
passed to the entmake function. If the entmake function is able to successfully create the new 
object, an entity data list is returned. If not, nil is returned. 

The following shows the syntax of the entmake function: 


(entmake [entlist]) 


The entlist argument represents the entity data list of the object to be created, and it is an 
optional argument. The list must contain all required dotted pairs to define the object and its 
properties. 

The following examples show how to create an entity data list with the list and cons func- 
tions, and then use the resulting list to create an object with the enmake function: 


; Creates a new circle at 2.5,3.5 with a radius of 0.75 
(setq cenPt (list 2.5 3.5 0.0) 
rad 0.75) 
(entmake (list (cons © "CIRCLE") (cons 10 cenPt) (cons 40 rad))) 


; creates a new line from 0,0,0 to 2.5,3.5 
(setq startPt (list 0.0 0.0 0.0) 
endPt (list 2.5 3.5 0.0)) 
(entmake (list (cons © "LINE") (cons 10 startPt) (cons 11 endPt))) 


Figure 6.1 shows the result of the two previous examples. 


FIGURE 6.1 
Circle and line 
objects created 
with the entmake 
function 


Remember that the quote (') function can’t evaluate an atom, so you can’t use variables in 
a list that is defined with the quote function. The following examples show how to create an 
entity data list with the quote function, and then use the resulting list to create an object with 
the entmake function: 


; Creates a new circle at 2.5,3.5 with a radius of 0.75 
(entmake '((0 . "CIRCLE") (10 2.5 3.5 0.0) (40 . 0.75))) 


; creates a new line from 0,0,0 to 2.5,3.5 
(entmake '((0 . "LINE") (10 0.0 0.0 0.0) (11 2.5 3.5 0.0))) 


In addition to using the entmake function, you can create objects with the entmakex function. 
The difference between the entmake and entmakex function is that an owner isn’t assigned to 
the object created with the entmakex function. Owner assignment primarily affects the creation 
of nongraphical objects, as all graphical objects are assigned to the current space or named 
layout. 


ADDING OBJECTS TO A DRAWING 


WARNING Objects created with the entmake and entmakex functions don’t participate in 
undo recording like objects created with standard AutoCAD commands. Undo recording 
must be implemented in your function using the undo command, and its suboptions Begin 
and End. I provide an example of how to group functions into a single undo grouping in 
Chapter 9, “Catching and Handling Errors.” 


TIP Unless you need to drag an object onscreen, I recommend creating objects with the entmake 
function since it gives you greater control over the object being created. The entmake function 
(unlike commands executed with the command function) isn’t affected by the current running 
object snap settings. 


This exercise shows how to create a plan view of a machine screw with a slotted round head 
(see Figure 6.2): 


FIGURE 6.2 

Plan view of a #12- 
24 machine screw, 
slotted round head 


1. Create a new drawing. 


2. At the AutoCAD Command prompt, type the following and press Enter to create a new 
circle that has a center point of 0,0 and radius of 0.4075. 


(entmake '((@ . "CIRCLE") (10 © 0) (40 . 0.4075))) 


The dotted pair with the DXF group code 10 sets the center point of the circle, and the 
dotted pair with the DXF group code 40 sets the radius of the circle. 


3. Type the following and press Enter to create the two lines that define the top and bottom 
of the slot in the head of the screw: 


(entmake '((0 . "LINE") (10 -0.18 0.0275) (11 0.18 0.0275))) 
(entmake '((0 . "LINE") (10 -0.18 -9.0275) (11 0.18 -0.0275))) 


The dotted pair with the DXF group code 10 sets the start point of the line, and the dotted 
pair with the DXF group code 11 sets the endpoint of the line. 


4. Type the following and press Enter to create the two arcs that define the left and right 
edges of the slot in the head of the screw: 


(entmake '((0 . "ARC") (10 0.0032 0) (40 . 0.1853) 
(50 . 2.99261) (51 . 3.29058))) 

(entmake '((0 . "ARC") (10 -0.0032 0) (40 . 0.1853) 
(50 . 6.13431) (51 . 0.148875))) 


The dotted pair with the DXF group code 10 sets the center point, DXF group code 40 sets 
the radius, DXF group code 50 sets the start angle (in radians), and DXF group code 51 sets 
the end angle (in radians) for each arc. 
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Selecting Objects 


AutoLISP enables you to step through the objects in a drawing or allow the user to interactively 
select one or more objects in the drawing area. Based on the selection technique used, an ename 
is returned; otherwise, a selection set (ssname) is returned that can contain one or more objects. 


Selecting an Individual Object 

AutoLISP provides two different techniques that can be used to select an individual object 
within a drawing—through code or via user interaction. When you want to work with the most 
recent object or step through all of the objects in a drawing, you don’t need any input from the 
user. The AutoLISP functions entlast and entnext can be used to get an individual object 
without any input from the user. If you do want to allow the user to interactively select an indi- 
vidual object, you can use the entsel and nentsel functions. 


SELECTING AN OBJECT THROUGH CODE 


The entlast function returns the entity name of the last graphical object added to a drawing 
and doesn’t require any arguments. This function can be helpful in getting the entity name for a 
new object created with the entmake function. 


; Create an arc with a center point of -1,1, radius of 1.5, 

3 a start angle of 315, and end angle of 135 

(entmake '((0 . "ARC")(10 -1.0 1.0 0.0)(40 . 1.5)(50 . 5.49779)(51 . 2.35619))) 
((@ . "ARC") (10 -1.0 1.0 0.0) (40 . 1.41421) (50 . 5.49779) (51 . 2.35619)) 


(setq entityName (entlast) ) 
<Entity name: 7ff72292cc10> 


The entnext function allows you to traverse a drawing from the first drawn to most recently 
added graphical object. When entnext is called without an argument, it returns the ename of 
the oldest graphical object in the drawing. If the function is passed a valid ename, the ename of 
the object drawn after the one passed to the function is returned. The following shows the syn- 
tax of the entnext function: 


(entnext [ename]) 


The ename argument is optional and represents the entity name of an object. The function 
returns the name of the next object in the drawing. When no ename argument is provided, the 
entity name of the first graphical object in the drawing is returned. 

The following example code uses the entnext function to step through and list the type of 
each object in the current drawing: 


; Lists the DXF group code © value for each object in the drawing 
(defun c:listobjects ( / ) 

(prompt "\nObjects in this drawing:") 

(setq entityName (entnext) ) 
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(while entityName 
(prompt (strcat "\n" (cdr (assoc © (entget entityName) )))) 
(setq entityName (entnext entityName) ) 

) 

(princ) 


) 


Objects in this drawing: 
CIRCLE 
DIMENSION 
DIMENSION 
INSERT 
ATTRIB 
SEQEND 
CIRCLE 
VIEWPORT 
VIEWPORT 
CIRCLE 
DIMENSION 
ARC 


The previous example used the entget function to return an entity data list of an object. 
I explain how to use this function later, in the “Updating an Object’s Properties with an Entity 
Data List” section. 


SELECTING AN OBJECT INTERACTIVELY 


The user can select a single object in the drawing area using the entsel and nentsel functions. 
The entsel function returns a list of two values: the entity name of the object selected and the 
center point of the pick box when the object was selected. nil is returned by the entsel func- 
tion if an object isn’t selected as the result of either the user picking in an empty area of the 
drawing or pressing Enter. 

The nentsel function is similar to entsel except that nentsel allows you to select a suben- 
tity within an object, such as an old-style polyline, dimension, or block. When a subentity in an 
object is selected with the nentsel function, a list of four elements is returned (in this order): 


@ The entity name of the subentity 

@ The point picked in the drawing 

@ A transformation matrix for the subentity 

@ Theentity name of the parent object of the subentity 

The following shows the syntax of the entsel and nentsel functions: 


(entsel [prompt]) 
(nentsel [prompt]) 
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The prompt argument is optional and represents the message (a string) that should be dis- 
played to the user when they are asked to select an object. If a prompt is not provided, the 
default prompt message of Select object: is displayed. 

The following examples show how to select an object with the entsel function: 


; Prompts the user to select an individual object 
(setq entlist (entsel "\nSelect an object: ")) 
(<Entity name: 7ff72292cc10> (-0.75599 2.48144 0.0)) 


; Uses the car function to get the entity name returned by entsel 
(setq entityName (car entlist) ) 
<Entity name: 7ff72292cc10> 


; Uses the cadr function to get the coordinate value returned by entsel 
(setq pickPoint (cadr entlist) ) 
(-0.75599 2.48144 0.0) 


Working with Selection Sets 


A selection set, sometimes known as a selection set name or ssname for short, is a temporary 
container that holds a reference to objects in a drawing. AutoLISP represents a selection set with 
the PICKFIRST data type. You get a selection set, commonly based on the objects in a drawing 
that the user wants to modify or interact with. For example, when you see the Select objects: 
prompt AutoCAD is asking you to select the objects in the drawing you want to work with and 
it gets a selection set containing the objects you selected in return. 

In addition to getting a selection set based on user input, you can create a selection set manu- 
ally and add objects to it. You might want to create a function that steps through a drawing and 
locates all the objects on a specific layer, and then returns a selection set that the next function 
can work with. Once a selection set is created, you can add additional objects or remove objects 
that don’t meet the requirements you want to work with. A selection set makes it efficient to 
query and modify a large number of objects. 


CREATING A SELECTION SET 


The most common way to create a selection set is to simply prompt the user to select objects in 
the drawing. The entsel and nentsel functions allow you to select a single object, but typi- 
cally you will want to allow the user to select more than one object at a time. The ssget function 
allows the user to interactively select objects in a drawing using the selection methods that are 
commonly available at the Select objects: prompt. The ssget function can also be used to 
create a selection set without any user input. The ssget function returns a PICKSET value if at 
least one object was selected or returns nil if no objects were selected. 


NOTE Unlike the entsel and nentsel functions, the ssget function doesn’t have a prompt 
argument. If you want a lead-in to the Select objects: prompt that ssget displays, you will 
need to display one with the prompt or princ function. 


The following shows the syntax of the ssget function: 


(ssget [method] [pointi [point2]] [points] [filter]) 
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Here are the arguments: 


method The method argument is optional and represents the selection method that should 
be used to create the selection set. Many of the selection methods available are similar 

to those found at the Select objects: prompt, but additional ones are available from 
AutoLISP. Table 6.5 lists some of the common selection methods available; for a full list of 
options search on “ssget” in the AutoCAD Help system. 


TABLE 6.5: ssget selection methods 


SELECTION METHOD DESCRIPTION 


C Crossing window selection 

CP Crossing polygon selection 

L Last object selection 

P Previous selection set 

WwW Window selection 

WP Window polygon selection 

X All entities in the database; locked and frozen also 
5 Single object selection 


point1 The point1 argument is an optional point list that is used to select the topmost 
object in the draw order at the specified point. This argument is also used to specify the first 
corner of a crossing window or window selection. 


point2 The point2 argument is an optional point list that is used to specify the second 
point for the crossing window or window selection. 


points The points argument is an optional list that contains several point lists; it is used to 
specify the points of a fence, crossing polygon, or window polygon selection. 


filter The filter argument is an optional association list that is similar to an entity data 
list, but it can also include comparison and grouping operators. Later in this chapter I explain 
how to create and use selection-set filters; see the sections “Filtering Selected Objects” and 
“Selecting Objects Based on XData.” 


The following examples show how to select objects with the ssget function; the returned 
values will vary based on the drawing you have open. Open a drawing with some objects in it 
before trying these examples: 


; Freely lets the user to select objects 
(setq ss (ssget)) 
Select objects: Specify the first corner of the selection window 
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Specify opposite corner: Specify a second point to define the selection window 
7 found 

Select objects: Press Enter to end object selection 

<Selection set: 4d> 


; Freely lets the user to select a single object 
(setq ssPt (ssget "_:S")) 
<Selection set: lcd> 


; Selects the last object drawn at 0,0,0 
(setq ssPt (ssget '(0 0 0))) 

<Selection set: a9> 

1 found 

Select objects: 


; Selects all objects that intersect 0,0,0 and not just the topmost object 
(setq ssC (ssget "_C" '(0 0 0) '(0 © 0))) 

<Selection set: be> 

3 found 

Select objects: 


; Selects objects with fence selection crossing (0,0), (0,6), (12,9), and (12,0) 
(setq ssF (ssget "_F" '((0 0)(0 6)(12 9)(12 0)))) 
<Selection set: 190> 


TIP A limited number of selection sets can exist in memory while a drawing remains open; a 
total of 128 selection sets can be active at one time—the number of selection sets that have been 
created and assigned to different variables without the variable being set back to nil. Once this 
limit is reached, no new selection sets can be created. I recommend defining any variables that 
are assigned a selection set as being local to a function, except when you may need to access a 
selection set across multiple functions. It is always better to pass values and selection sets to a 
function than to rely on global variables. If you use global variables for selection sets, you should 
set all variables to ni l when they are no longer needed in order to remove them from memory. 


The ssget function also supports implied selection with the I selection method. Just like 
many AutoCAD commands, such as move and copy, implied selection allows a user to select 
objects before starting your custom program. If no objects are selected when you use the state- 
ment (ssget "_I"), the ssget function returns nil. You can then test for the nil return value, 
and if nil is returned, you can prompt the user to select objects. 

In addition to using the ssget function to get the objects selected with implied selection, 
you can use the ssgetfirst function to select objects that have their grips displayed. Grips 
are displayed only when no custom program or command is active and the user selects objects 
in the drawing area. The ssgetfirst function returns a list of two elements. The first element 
always returns nil in recent releases, but in earlier releases it returned a pickfirst value that 
represented the objects that displayed grips and weren't selected. The second element returns a 
pickfirst value that represents any objects that are currently selected and have their grips dis- 
played. The ssgetfirst function doesn’t accept any arguments. 
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While the ssgetfirst function is used to get objects that are currently selected and have 
their grips displayed, you can use the sssetfirst function to select and display the grips for 
specific objects. The following shows the syntax of the ssset first function: 


(sssetfirst gripset [pickset]) 


Here are the arguments: 


gripset The gripset argument no longer affects the outcome of the sssetfirst function. 
In earlier releases, this argument required a pickset value that would be used to display the 
grips of objects but not select them. In recent releases, nil should always pass this argument. 


pickset The pickset argument is optional and must be a pickfirst value that contains 
the objects that should be selected and have their grips displayed. 


The following examples show how to select and display the grips for the last object ina 
drawing with the sssetfirst function: 


; Creates a line object that is drawn from 0,0 to -5,5 with a color of red 
(entmake '((0 . "line")(10 0.0 0.0)(11 -5.0 5.0)(62 . 1))) 
((O . "lLine") (10 0.0 0.0) (11 -5.0 5.0) (62 . 1)) 


; Displays grips for and selects the line that was added 
(sssetfirst nil (ssget "L")) 
(nil <Selection set: 353>) 


; Erases the object with grips displayed 
(command "._erase" (cadr (ssgetfirst)) "") 
nil 


NOTE The ssnamex function can be used to get information about how the objects in a selec- 
tion set were added, as well as how the selection set was created. This includes selection sets 
created with the ssget, ssget first, and ssadd functions. The value returned by the ssnamex 
function is a list. For more information on the ssnamex function, search on “ssnamex” in the 
AutoCAD Help system. 


MANAGING OBJECTS IN A SELECTION SET 


After the user has been prompted to select objects, the resulting selection set can be revised by 
adding or removing objects. Objects that aren’t in the selection set but are in the drawing can be 
added to the selection set using the ssadd function. If the user selected an object that shouldn't 
be in the selection set, it can be removed using the ssdel function. The ssadd and ssdel 
functions return the selection set that they are passed if the function was successful; 

otherwise, the function returns nil. 


NOTE Inaddition to adding objects to a selection set with the ssadd function, you can use the 
function to create a new selection set without user interaction. 


Normally when an object is selected in the drawing, it is added to a selection set once, as dupli- 
cate entries aren't allowed. Before adding an object to a selection set with the ssadd function, 
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you can determine if an object is already present in a selection set with the ssmemb function. 
Duplicate objects in a selection set isn’t a problem, but it could cause an issue if your program is 
extracting information from a drawing or could result in your program taking longer to complete. 
The ssmemb function returns the ename of the object if it is present in the selection set; otherwise, 
the function returns nil. 

The following shows the syntax of the ssadd, ssdel, and ssmemb functions: 


(ssadd ename [ss]) 
(ssdel ename ss) 
(ssmemb ename ss) 


The arguments are as follows: 


ename When used with the ssadd or ssdel function, the ename argument represents the 
entity name that should be added to or removed from the selection set. When used with 
the ssmemb function, the ename argument specifies a particular ename to check for in the 
selection set. 


ss When you want to add, remove, or check for the existence of an entity name in a selec- 
tion set, the ss argument specifies the selection set for the operation. The ss argument is 
optional for the ssadd function. 


The following examples show how to add and remove objects in a selection set using the 
ssadd, ssdel, and ssmemb functions: 


; Create a line object 
(entmake '((0 . "line")(10 0.0 0.0)(11 -5.0 5.0)(62 . 1))) 
((O . "line") (10 0.0 0.0) (11 -5.0 5.0) (62 . 1)) 


; Add the line to the selection set 
(setq ssl (ssadd (entlast) ssi1)) 
<Selection set: al> 


; Determine if the last graphical entity is in the selection set 
(ssmemb (entlast) ss1) 
<Entity name: 7ff6a1704f00> 


; Remove the last entity from the selection set 
(ssdel (entlast) ssl) 
<Selection set: al> 


; Determine if the last graphical entity is in the selection set 
(ssmemb (entlast) ss1) 
nil 


STEPPING THROUGH A SELECTION SET 


Selection sets contain the objects the user selected in the drawing for query or modification and 
might include one to several thousand objects. You can use the repeat or while looping func- 
tions in combination with the sslength and ssname functions to step through and access each 
object in a selection set. The ss length function returns the number of objects in a selection set 
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as an integer, whereas the ssname function is used to return the entity name of an object located 
at a specific index within a selection set. The index of the first object in a selection set is 0. As 
part of a looping statement, you increment an integer value by 1 to get the next object until you 
reach the last object in the selection set. If an object isn’t at the specified index in a selection set 
when using the ssname function, nil is returned. 

The following shows the syntax of the ss length function: 


(sslength ss) 


The ss argument represents the selection set from which you want to get the number of 
objects. 
The following shows the syntax of the ssname function: 


(ssname ss index) 


Its arguments are as follows: 


ss The ss argument represents the selection set from which you want to get an entity name 
at a specific index. 


index The index argument represents the location within the selection set specified by 
the ss argument that has the object you want to get. 0 is the index of the first object in the 
selection set. 


The following examples show how to get the number of objects in a selection set and get an 
object from a selection set with the ssLength and ssname functions: 


; Get a selection set 

(setq ssNew (ssget) ) 

Select objects: Specify the first corner of the object-selection window 

Specify opposite corner: Specify the other corner of the object-selection window 
9 found 

Select objects: Press Enter to end object selection 

<Selection set: 13> 


; Output the number of objects in a selection set 
(prompt (strcat "\nSelection set length: " (itoa (sslength ssNew) )))(princ) 
Selection set length: 9 


; Get the entity name of the first object in the selection set 
(ssname ssNew 0) 
<Entity name: 7ff63f005d90> 


This exercise shows how to create and step through a selection set: 


1. Open a drawing with some objects, or create a new drawing and then add some objects to 
the drawing. 


2. At the AutoCAD Command prompt, type the following and press Enter to create a selec- 
tion set and assign it to the sset variable: 


(prompt "\nSelect objects to list: ") 
(setq sset (ssget)) 
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3. Type the following and press Enter to create a new circle and then add the new circle to 
the selection set: 


(entmake '((0 . "circle")(10 0.0 0.0)(40 . 2))) 
(if (= (ssmemb (entlast) sset) nil) 

(setq sset (ssadd (entlast) sset)) 
) 


While the circle shouldn't be part of the objects you selected, the code shows how to use 
a comparison to test the results of the ssmemb function. The new object is added only if it 
isn’t already part of the selection set. 


4. Type the following and press Enter to display the number of objects in the selection set: 


(prompt (strcat "\nObjects in selection set: " (itoa (sslength sset))))(princ) 


5. Type the following and press Enter to change the color of each object in the selection set: 


(setq cnt 0 clr 1) 
(while (> (sslength sset) cnt) 
(command "._change" (ssname sset cnt) "" "_p" "_c" clr "") 
(setq cnt (1+ cnt)) 
(setq clr (1+ clr)) 
(if (> clr 9)(setq clr 1)) 
) (princ) 


The colors assigned to the objects range from ACI 1 through 9, and reset back to 1 when 
the counter reaches 10. 


Filtering Selected Objects 


When selecting objects with the ssget function, you can control which objects are added to the 

selection set. A selection filter allows you to select objects of a specific type or even objects with 

certain property values. Selection filters are made up of dotted pairs and are similar to an entity 
data list. For example, the following selection filter will select all circles on the layer holes: 


'((0 . "circle")(8 . "holes")) 


As I mentioned earlier, the DXF group code 0 represents an object’s name and the DXF group 
code 8 represents the name of the layer an object is placed on. 

In addition to object names and properties, a selection filter can include logical grouping 
and comparison operators to create complex filters. Complex filters can be used to allow for the 
selection of several object types, such as both text and mtext objects, or allow for the selection of 
circles with a radius in a given range. Logical grouping and comparison operators are specified 
by string values with the DXF group code -4. For example, the following selection filter allows 
for the selection of circles with a radius in the range of 1 to 5: 


"C(O . "circle") 
(-4 . "<and")(-4 . "<=")(40 . 5.0)(-4 . ">=")(40 . 1.0)(-4 . "and>")) 


Selection filters support four logical grouping operators: and, or, not, and xor. Each logi- 
cal grouping operator used in a selection filter must have a beginning and an ending operator. 
Beginning operators start with the character < and ending operators end with the character >. 
In addition to logical operators, you can use seven different comparison operators in a selection 
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filter to evaluate the value of a property: = (equal to), != (not equal to), < (less than), > (greater 
than), <= (less than or equal to), >= (greater than or equal to), and * (wildcard for string 
comparisons). 

After defining a selection filter, you then pass it to the filter argument of the ssget 
function. 

This exercise shows how to use selection filters with the ssget function: 


1. Create a new drawing. Add some circles, arcs, and lines to the drawing. 


2. At the AutoCAD Command prompt, type (setq ssCircles (ssget '((0 . 
"circle")))) and press Enter. 


3. Atthe Select objects: prompt, select all the objects in the drawing. Notice only the 
circles are highlighted. Press Enter to end object selection. 


4. Type (command "._change" ssCircles "" "_p" "_c" 1 "") and press Enter to 
change the color of all circles to red. 


5. At the AutoCAD Command prompt, type (setq ssArcsLines (ssget '((-4 . "<or") 
(0 . "arc") (0 . "line")(-4 . "or>")))) and press Enter. Select some of the lines 
and arcs in the drawing. 


6. Type (command "._change" ssArcsLines "" "_p" "_c" 3 "") and press Enter to 
change the color of the selected objects to green. 


TIP On AutoCAD for Windows, you can use the filter command to create a filter selection 
and save it. Saving the filter adds it to the file named filter.nfl. You can use the AutoLISP 
statement (findfile "filter.nfl") to return the location of the file in the command-line 
window. Open the file with Notepad. The filter command writes the filter in two formats: 
as AutoLISP statements (:ai_lisp) and as a string description (:ai_str). You can copy the 
AutoLISP statements that are created to define an object selection filter for use with the ssget 
function. Although this technique can help simplify the testing and creation of complex selec- 
tion filters, it is undocumented and something I just figured out years ago when I first started 
learning AutoLISP. 


Modifying Objects 
The majority of time spent on a design isn’t related to creating new objects, but rather to modify- 
ing the objects that are already in a drawing. When you need to modify an object, you can use 
an AutoCAD command with the command function or directly with AutoLISP functions. Directly 
modifying an object provides you with more choices in the properties you can change and gives 
you more flexibility than using commands. 

Modifying objects with AutoCAD commands is similar to creating new objects, with the 
exception of the way you pass objects to the command. Based on the command, you will need to 
pass one of the following to the Select object: or Select objects: prompt to select objects: 


Entity Name (ename) An ename can be used when a command expects or you want to 
modify a single object. 


Selection Set (ssname) An ssname can be used to pass several objects to a command that 
can modify one or more objects. 
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I explained how to select objects and work with selection sets in the “Selecting Objects” sec- 
tion earlier in this chapter. 

The following are examples that demonstrate how to modify objects with AutoCAD 
commands: 


; Changes the selected objects to the color red 
(prompt "\nSelect objects to change to red: ") 
(setq ss (ssget)) 

(command LLa change" ss m n p" " c" 1 mit) 


; Scale the last graphical object by a user-defined base point and a factor of 2 
(command "._scale" (entlast) "" PAUSE 2) 


In this section, I explain how to work with entity names and directly modify an object with- 
out using the command function. The properties of an object can be queried or edited one at a 
time, or you can manipulate several properties of an object by changing the entity data list that 
represents the object. 


Listing and Changing the Properties of an Object Directly 
AutoLISP offers two different methods for modifying the properties of an object directly. The 
easier of the two methods is to use the object property functions that were introduced with 
AutoCAD 2012. These functions require less code than the legacy approach of getting and 
manipulating the entity data list of an object. The property-related functions are less cryptic 
than entity data list manipulation as well, because you don’t need to understand the various 
DXF group codes associated with a specific object. The downside to these functions is that they 
work only with AutoCAD 2012 and later, so if you need to support an earlier release you will 
need to manipulate entity data lists (which I cover in the next section). 

Table 6.6 lists the AutoLISP functions available in AutoCAD 2012 and later that can be used to 
list, get, and set the properties of an object. 


TABLE 6.6: AutoLISP object property functions 
FUNCTION DESCRIPTION 
dumpallproperties Returns all of the properties for the specified object 
getpropertyvalue Returns the current value of an object’s property 
setpropertyvalue Assigns a value to an object’s property 
ispropertyreadonly Returns T or nil based on whether an object property is read-only 
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The dumpallproperties function outputs the properties and their current values for an object 
to the command-line window. Some property values, such as StartPoint for a line or Position 
of a block reference, can be output as a single value or as three individual values. 
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The following shows the syntax of the dumpallproperties function: 
(dumpallproperties ename [mode]) 


Its arguments are as follows: 


ename The ename argument represents the entity name of the object for which you want to 
list properties. 


mode The mode argument is optional and represents how data types such as AcGePoint3d 
and AcGeVector3d are output. When mode is 0, a property such as Center is displayed as a 
single entry and not separate entries for the X, Y, and Z values of a property. For example, 
the following output is of the center point for a circle that has X, Y, and Z components to the 
value. The output shows all three components as part of a single property named Center. 


Center (type: AcGePoint3d) 
(LocalName: Center X;Center Y;Center Z) = 0.000000 5.000000 0.000000 


A value of 1 for mode displays each element of a value as separate entries. This is the default 
behavior when mode isn’t provided. The following output is of the same center point as 
before, but notice all three components of the point are expressed as separate properties with 
unique names: Center/X, Center/Y, and Center/Z. 


Center/X (type: double) (LocalName: Center X) = 0.000000 
Center/Y (type: double) (LocalName: Center Y) = 5.000000 
Center/Z (type: double) (LocalName: Center Z) = 0.000000 


The following examples show how to output the properties of an object with the 
dumpallproperties function: 


; Properties are output as a single entry 
(dumpallproperties (entlast) 1) 


; Properties are output as separate entries 
(dumpallproperties (entlast) ) 


Here is an example of the output created by the dumpallproperties function for a circle 
object. The output was generated with the expression (dumpallproperties (entlast) ): 


Begin dumping object (class: AcDbCircle) 
Annotative (type: bool) (LocalName: Annotative) = Failed to get value 
AnnotativeScale (type: AcString) (RO) 

(LocalName: Annotative scale) = Failed to get value 
Area (type: double) (RO) (LocalName: Area) = 12.566371 
BlockId (type: AcDbObjectId) (RO) = 7ff618a039f0 
CastShadows (type: bool) = 0 
Center/X (type: double) (LocalName: Center X) = 0.000000 
Center/Y (type: double) (LocalName: Center Y) = 5.000000 
Center/Z (type: double) (LocalName: Center Z) = 0.000000 
Circumference (type: double) (LocalName: Circumference) = 12.566371 
ClassName (type: AcString) (RO) = 
Closed (type: bool) (RO) (LocalName: Closed) = Failed to get value 
CollisionType (type: AcDb::CollisionType) (RO) = 1 
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Color (type: AcCmColor) (LocalName: Color) = BYLAYER 
Diameter (type: double) (LocalName: Diameter) = 4.000000 
EndParam (type: double) (RO) = 6.283185 
EndPoint/X (type: double) (RO) (LocalName: End X) = Failed to get value 
EndPoint/Y (type: double) (RO) (LocalName: End Y) = Failed to get value 
EndPoint/Z (type: double) (RO) (LocalName: End Z) = Failed to get value 
ExtensionDictionary (type: AcDbObjectId) (RO) = 0 
Handle (type: AcDbHandle) (RO) = 1f9 
HasFields (type: bool) (RO) = 0 
HasSaveVersionOverride (type: bool) = 0 
Hyperlinks (type: AcDbHyperlink*) 
IsA (type: AcRxClass*) (RO) = AcDbCircle 
IsAProxy (type: bool) (RO) = 0 
IsCancelling (type: bool) (RO) = 0 
IsEraseStatusToggled (type: bool) (RO) = 0 
IsErased (type: bool) (RO) = 0 
IsModified (type: bool) (RO) = 0 
IsModifiedGraphics (type: bool) (RO) = 0 
IsModifiedXData (type: bool) (RO) = 0 
IsNewObject (type: bool) (RO) = 0 
IsNotifyEnabled (type: bool) (RO) = 0 
IsNotifying (type: bool) (RO) = 0 
IsObjectIdsInFlux (type: bool) (RO) 
IsPeriodic (type: bool) (RO) = 1 
IsPersistent (type: bool) (RO) = 1 
IsPlanar (type: bool) (RO) = 1 
IsReadEnabled (type: bool) (RO) = 1 
IsReallyClosing (type: bool) (RO) = 1 
IsTransactionResident (type: bool) (RO) = 0 
IsUndoing (type: bool) (RO) = 0 
IsWriteEnabled (type: bool) (RO) = 0 
LayerId (type: AcDbObjectId) (LocalName: Layer) = 7ff618a03900 
LineWeight (type: AcDb::LineWeight) (LocalName: Lineweight) = -1 
LinetypeId (type: AcDbObjectId) (LocalName: Linetype) = 7ff618a03950 
LinetypeScale (type: double) (LocalName: Linetype scale) = 1.000000 
LocalizedName (type: AcString) (RO) = Circle 
MaterialId (type: AcDbObjectId) (LocalName: Material) = 7ff618a03de0 
MergeStyle (type: AcDb::DuplicateRecordCloning) (RO) = 1 
Normal/X (type: double) (RO) (LocalName: Normal X) = 0.000000 
Normal/Y (type: double) (RO) (LocalName: Normal Y) = 0.000000 
Normal/Z (type: double) (RO) (LocalName: Normal Z) = 1.000000 
ObjectId (type: AcDbObjectId) (RO) = 7ff618a0c090 
OwnerId (type: AcDbObjectId) (RO) = 7ff618a039f0 
PlotStyleName (type: AcString) (LocalName: Plot style) = ByLayer 
Radius (type: double) (LocalName: Radius) = 2.000000 
ReceiveShadows (type: bool) = 0 
ShadowDisplay (type: AcDb::ShadowFlags) (RO) 
(LocalName: Shadow Display) = Failed to get value 


I 
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StartParam (type: double) (RO) = 0.000000 

StartPoint/X (type: double) (RO) (LocalName: Start X) = Failed to get value 
StartPoint/Y (type: double) (RO) (LocalName: Start Y) = Failed to get value 
StartPoint/Z (type: double) (RO) (LocalName: Start Z) = Failed to get value 
Thickness (type: double) (LocalName: Thickness) = 0.000000 

Transparency (type: AcCmTransparency) (LocalName: Transparency) = 0 

Visible (type: AcDb::Visibility) = 0 

End object dump 


Now that you have seen an example output of an object with the dumpallproperties func- 
tion, it is time to take a closer look at an individual property. The following line shows the Area 
property from the previous output. Table 6.7 explains the elements. 


Area (type: double) (RO) (LocalName: Area) = 12.566371 


TABLE 6.7: dumpallproperties Area property description 
ITEM DESCRIPTION 
Area The global name of the object’s property. 
(type: double) The data type for the value for the property. 
(RO) The property is read-only. 
(LocalName: Area) The local name of the object property. 
= 12.566371 The value of the property. 


NOTE The data types that are listed by the dumpallproperties function aren't the same as 
those that you might be accustomed to for AutoLISP. For example, an AcString returns a string 
value, double is a real value, and AcDbObjectId is translated to an ename. 


GETTING AND SETTING THE VALUE OF AN OBJECT PROPERTY 


The getpropertyvalue and setpropertyvalue functions allow you to set an object’s property. 
Use the dumpallproperties function on an ename to see the properties available for an object 
and the type of data that is expected. 


The following shows the syntax of the getpropertyvalue and setpropertyvalue functions: 


(getpropertyvalue ename property) 
(getpropertyvalue ename collection index subproperty) 


(setpropertyvalue ename property value) 
(setpropertyvalue ename collection index subproperty value) 
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Here are the arguments: 


ename The ename argument represents the entity name of the object for which you want to 
get or set a property value. 


property Use the property argument to specify a single-value property. 


collection Use the collection argument to specify a property that contains more than 
one value, such as vertices of a polyline. 


index Use the index argument to specify an item within a property collection. 


subproperty Use the subproperty argument to specify a subproperty within a property 
collection. 


value The value argument represents the value you want to assign the property. 


The following examples show how to get and set the property values of a circle and a poly- 
line with the getpropertyvalue and setpropertyvalue functions: 


; Creates a circle and polyline 
(command "._circle" "0,0" 1) 
(setq circ (entlast) ) 


(command ",_pline" "2,3" "1,4" W-3,-2" mr) 
(setq pline (entlast)) 


; Outputs the radius of the circle 
(prompt (strcat "\nRadius: " (rtos (getpropertyvalue circ "radius")))) 
Radius: 1.0000nil 


; Outputs the last vertex of the polyline 
(prompt (strcat "\nVertex 3: " 
(vl-princ-to-string (getpropertyvalue pline "vertices" 2 "position")) 
)) 
Vertex 3: (-3.0 -2.0 0.0)nil 


; Changes the radius of the circle 
(setpropertyvalue circ "radius" 0.5) 
nil 


; Changes the position of the polyline's last vertex to the center of the circle 

(setq cenPt (getpropertyvalue circ "center") ) 

(setpropertyvalue pline "vertices" 2 "position" cenPt) 

nil 

Before you try to change a property value with setpropertyva Lue, use the ispropertyreadonly 
function to determine if the property is read-only. ispropertyreadonly returns 1 if a property is 


read-only; 0 is returned when a property can be changed. The following shows the syntax of the 
ispropertyreadonly function: 


(ispropertyreadonly ename property) 
(ispropertyreadonly ename collection index subproperty) 
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The following examples show how to determine if a property for a line object is read-only 
with the ispropertyreadonly: 


; Creates a line 
(command "._line" "2,2" "5,6" "") 
(setq line (entlast) ) 


; Tests to see if the Angle property is read-only 
(ispropertyreadonly line "angle") 
iL, 


; Tests to see if the StartPoint property is read-only 
(ispropertyreadonly line "startpoint") 
(0) 


This exercise shows how to modify the properties of a circle, line, and text object: 
1. Create a new drawing. 


2. Draw a circle (center at 4,5 and a radius of 3), a line (starts at -1,2 and ends at 8,15), anda 
single-line text object (insertion point of 0,0, a justification of middle center, a height of 4, 
and a value of A). The left side of Figure. 6.3 shows what the objects look like before they 
are modified. 


FIGURE 6.3 
Basics of a callout 
balloon 


A 


3. At the AutoCAD Command prompt, type the following, pressing Enter after each line 
and selecting the object mentioned in the prompt: 
(setq circ (car (entsel "\nSelect circle: "))) 
(setq line (car (entsel "\nSelect line: "))) 
(setq text (car (entsel "\nSelect text: "))) 


4. Type (dumpallproperties circ 1) and press Enter to display the properties of the 
circle. Do the same with the line and text variables. 


5. Press F2 on Windows or Fn-F2 on Mac OS to expand the command-line window (or 
display the Text History window on Windows if the command-line window is docked). 
Review the properties and values of the objects. 


6. Type the following and press Enter to change the circle’s color to cyan, the line’s color to 
blue, and the text’s color to red: 


(setpropertyvalue circ "color" 4) 
(setpropertyvalue line "color" 5) 
(setpropertyvalue text "color" 1) 
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7. Type the following and press Enter to change the line’s start point and the text's align- 
ment point to the circle’s center point: 


(setpropertyvalue line "startpoint" (getpropertyvalue circ "center") ) 
(setpropertyvalue text "alignmentpoint" (getpropertyvalue circ "center")) 


8. Type the following and press Enter to shorten the line so it intersects with the circle’s 
radius: 


(setq ang (angle (getpropertyvalue line "startpoint") 
(getpropertyvalue line "endpoint") 


)) 
(setq newPt (polar (getpropertyvalue circ "center") 
ang 
(getpropertyvalue circ "radius") 
)) 


(setpropertyvalue line "startpoint" newPt) 


The three modified objects should now look like those on the right side of Figure 6.3. 


Updating an Object’s Properties with an Entity Data List 

Although the functions I mentioned in the previous section make working with object proper- 
ties easier in recent releases, you should also understand how to modify the properties of an 
object with an entity data list. There are three main reasons why I recommend this: 


@ Older programs modify objects using entity data lists; understanding how to update entity 
data lists will make it easier for you to update an existing program. 


@ AutoCAD releases earlier than AutoCAD 2012 only support editing the properties of 
objects through entity data lists. 


@ Entity data lists are used to create and define selection filters. 


The entget function is used to return the entity data list of an object. Once you have an 
entity data list, you can then use the assoc function to locate the dotted pair that has the DXF 
group code as the key element you are interested in querying or modifying. After a dotted pair 
is retuned, you can then use the car function to get the key element of the list and the cdr func- 
tion to get the value element of the dotted pair. 

If you want to replace a dotted pair in an entity data list to change the value of a property, 
use the subst function. Then, after you update an entity data list, the changed entity data list 
must be committed to the object with the entmod function. After calling entmod, you should call 
the entupd function with the same object that was passed to the entget function to update the 
object’s graphics onscreen. 

The following shows the syntax of the entget, entmod, and entupd functions: 


(entget ename [apps]) 
(entmod ename) 
(entupd ename) 
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Here are the arguments: 


ename The ename argument specifies the entity name of the object you want update or to get 
an entity data list for. 


apps The apps argument is optional; it is a string value that specifies the application name 
of an extended data (XData) list that you want to retrieve. XData is custom information that 
can be attached to an object, such as a link to an external data source or date when an object 
was revised, and is similar to an entity data list associated with an ename. If an XData list 
with the application name is attached to the object, a list with both the entity data and XData 
is returned. Otherwise, just the entity data list for the object is returned. For more informa- 
tion on XData, see the “Extending the Information of an Object” section later in this chapter. 


The following examples show how to get an entity data list with entget, modify an entity 
data list with entmod, and update an object in the drawing area with entupd: 


; Creates a new ellipse and gets the new object's entity name 
(entmake '((0 . "ELLIPSE") (100 . "AcDbEntity") (100 . "AcDbEllipse"') 
(10 6.0 2.0 0.0) (11 -4.0 0.0 0.0) 
(40 . 0.5) (41 . 0.0) (42 . 6.28319))) 
(setq entityName (entlast) ) 
<Entity name: 7ff6bc905dc0> 


; Gets the entity data list for the last object, which is the ellipse 
(setq entityData (entget entityName) ) 
((-1 . <Entity name: 7ff6bc905dcO>) (© . "ELLIPSE") 
(330 . <Entity name: 7ff6bc9039f0>) (5 . "1D4") (100 . "AcDbEntity") 
(67 . ©) (410 . "Model") (8 . "0") (100 . "AcDbEllipse") 
(10 6.0 2.0 0.0) (11 -4.0 0.0 0.0) (210 0.0 0.0 1.0) (40 . 0.5) 
(41 . 0.0) (42 . 6.28319)) 


; Gets the object's insertion/center point, center of the ellipse 
(setq dxfGroupCode10 (assoc 10 entityData) ) 
(10 6.0 2.0 0.0) 


; Gets the object's color; in this case nil is returned as a color isn't assigned 
(setq dxfGroupCode62 (assoc 62 entityData) ) 
nil 


; Changes the object's center point to 0,0 
(setq entityData (subst '(10 0.0 0.0 0.0) dxfGroupCodel0 entityData) ) 
(10 6.0 2.0 0.0) 


; Appends a dotted pair to change the object's color 
(setq entityData (append entityData '((62 . 3)))) 


; Modifies the object with the revised entity data list 
(entmod entityData) 
(entupd entityName) 
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Listing 6.1 is a set of two custom functions that simplify the process of updating an object 
using entity data lists and DXF group codes. 


LISTING 6.1: DXF helper functions 


; Returns the value of the specified DXF group code for the supplied entity name 
(defun Get-DXF-Value (entityName DXFcode / ) 
(cdr (assoc DXFcode (entget entityName) )) 


; Sets the value of the specified DXF group code for the supplied entity name 
(defun Set-DXF-Value (entityName DXFcode newValue / entityData newPropList 
oldPropList) 
; Gets the entity data list for the object 
setq entityData (entget entityName) ) 


; Creates the dotted pair for the new property value 

setq newPropList (cons DXFcode newValue) ) 

if (setq oldPropList (assoc DXFcode entityData) ) 

(setq entityData (subst newPropList oldPropList entityData) ) 
(setq entityData (append entityData (list newPropList))) 


; Updates the object's entity data list 
entmod entityData) 


; Refreshes the object onscreen 
entupd entityName) 


; Returns the new entity data list 
entityData 
) 


The custom functions in Listing 6.1 are used in the next exercise. 
This exercise shows how to modify the properties of a circle, line, and text object: 


1. Create a new drawing. 


2. Use the appload command to load the ch06_listings. lsp file once it is downloaded 
from www. sybex.com/go/autocadcustomization. 


3. Draw a circle (center at 4,5 and a radius of 3), a line (starts at -1,2 and ends at 8,15), and a 
single-line text object (insertion point of 0,0, a justification of middle center, a height of 4, 
and a value of A). Refer back to Figure 6.3; the left side shows what the objects look like 
before they are modified. 


4. At the AutoCAD Command prompt, type the code in Listing 6.1. This will allow you to 
use the custom functions to make it easier to modify the properties of an object with an 
entity data list. 


10. 
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Type the following, pressing Enter after each line, and select the object mentioned in the 
prompt. 


(setq circ (car (entsel "\nSelect circle: "))) 
(setq line (car (entsel "\nSelect line: "))) 
(setq text (car (entsel "\nSelect text: "))) 


Type (dumpallproperties circ 1) and press Enter to display the properties of the 
circle. Do the same with the line and text variables. 


Press F2 on Windows or Fn-F2 on Mac OS to expand the command-line window (or 
display the Text History window on Windows if the command-line window is docked). 
Review the properties and values of the objects. 


Type the following and press Enter to change the circle’s color to cyan, the line’s color to 
blue, and the text’s color to red: 


(Set-DXF-Value circ 62 4) 
(Set-DXF-Value line 62 5) 
(Set-DXF-Value text 62 1) 


Type the following and press Enter to change the line’s start point and the text's align- 
ment point to the circle’s center point: 

(Set-DXF-Value line 10 (Get-DXF-Value circ 10)) 

(Set-DXF-Value text 11 (Get-DXF-Value circ 10)) 

Type the following and press Enter to shorten the line so it intersects with the circle’s 
radius: 


(setq ang (angle (Get-DXF-Value line 10) 
(Get-DXF-Value line 11) 


)) 
(setq newPt (polar (Get-DXF-Value circ 10) 
ang 
(Get-DXF-Value circ 40) 
)) 


(Set-DXF-Value line 10 newPt) 


The three modified objects should now look like those on the right side of Figure 6.3. 


Deleting an Object 


An object that is no longer needed can be deleted from a drawing with the AutoLISP entdel 
function. Deleting an object from a drawing with the entdel function removes it from the dis- 
play but doesn’t remove the object from the drawing immediately. It flags an object for removal; 
the object is removed when the drawing is saved and then closed. You can use the entdel func- 
tion a second time to restore the object while the drawing remains open. Using the AutoCAD u or 
undo command will also restore an object that was flagged for removal with the entdel function. 
Objects removed with the erase command can also be restored with the entdel function. 


NOTE = Theentdel function can be used to remove only graphical objects and objects associated 
with a dictionary, not symbol-table entries such as layers and block definitions. I discuss more 
about working with nongraphical objects in Chapter 7. 
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The following shows the syntax of the entdel function: 
(entdel ename) 


The ename argument represents the entity name of the object to flag for deletion or restore. 
The following examples show how to remove an object with the entdel function: 


; Gets the last object added to the drawing 

(setq en (entlast) ) 

<Entity name: 7ff618a0be20> 

; Deletes the object assigned to the en variable 
(entdel en) 

<Entity name: 7ff618a0be20> 

; Restores the object assigned to the en variable 
(entdel en) 

<Entity name: 7ff618a0be20> 


Highlighting Objects 

Object highlighting is the feedback technique that AutoCAD uses to indicate which objects have 
been selected in the drawing area and are ready to be interacted with or modified. While high- 
lighting is a great way to let a user know which objects will be modified, it can also impact the 
performance of a program when a large number of objects are selected. You can turn off general 
object-selection highlighting with the highlight system variable. 

The AutoLISP redraw function, not the same as the redraw command, can be used to high- 
light individual objects. Highlighting generated by the redraw function can be undone, either 
with the redraw function or the AutoCAD regen command. In addition to highlighting an 
object, the redraw function can be used to temporarily hide and then redisplay an object. 

The following shows the syntax of the redraw function: 


(redraw [ename [mode] ]) 


Here are the arguments: 
ename The ename argument represents the entity name of the object to highlight or display. 


mode The mode argument is an integer that specifies the highlight or display state of the 
object. Use the values 1 (show) and 2 (hide) to control the display of an object. The values 
3 (on) and 4 (off) control the highlighting of the object. 


The following examples show how to highlight and display an object with the redraw 
function: 


; Highlights the last graphical object in the drawing 
(redraw (entlast) 3) 

; Unighlights the object 

(redraw (entlast) 4) 

; Hides the object 

(redraw (entlast) 2) 

; Shows the object 

(redraw (entlast) 1) 
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Working with Complex Objects 


Some objects in AutoCAD represent basic geometry such as circles and lines, whereas other 
objects are complex and made up of several objects. Complex objects require a bit more work 
to create and modify with AutoLISP. The two most common complex objects that you will find 
yourself working with are polylines and block references. 


) Real World Scenario 
THINKING AHEAD 


Your boss comes to you and asks for a mock furniture layout for a new area in the office that your 
company is planning to renovate. Typically this is all handled by an outside firm, but your boss 
figures you can get the job done faster. After all, your boss is more concerned with getting the office 
layout completed than how to do the actual work. 


Knowing that he’s likely to ask for a layout of the whole floor—not just that small renovation area— 
you create blocks with attributes that allow you to get a quantity for each component. Instead of 
counting each component manually and then adding the component quantity to a table grid in the 
drawing, you automate the process. Using AutoLISP, you read the information from the attributes 
of each block and create an aggregated set of information that you use to create the table grid. 
Going forward, AutoLISP makes it easy to revise the table grid when your boss wants to change 
the layout at a later date. 


Creating and Modifying Polylines 

AutoCAD drawings can contain two different types of polylines; old-style (legacy) and light- 
weight. Old-style polylines were the first type of polylines that were introduced in an early 
release of AutoCAD. An old-style polyline is composed of several objects: a main polyline 
object, vertex objects that define each vertex of the polyline, and a seqend object that defines 
the end of the polyline. Old-style polylines can be 2D or 3D and contain straight or curved 
segments. 

Lightweight polylines, introduced with AutoCAD Release 14, take up less memory than old- 
style polylines but are 2D only. All 3D polylines are created using old-style polylines. Unlike 
old-style polylines, multiple objects aren’t used to define a lightweight polyline. Most polylines 
created since AutoCAD Release 14 are most likely of the lightweight type. The plLinetype sys- 
tem variable controls the type of polyline that is created with the pLine command. 

The following example creates an old-style polyline that has the coordinate values (0 0), (5 5), 
(10 5), and (10 0) with the entmake function: 


; Creates the base polyline object 
(entmake '((0 . "POLYLINE") (100 . "AcDbEntity") (100 . "AcDb2dPolyline") 
(10 0.0 0.0 0.0) (70 . 1))) 
((@ . "POLYLINE") (100 . "AcDbEntity") (100 . "AcDb2dPolyline") (10 0.0 0.0 0.0) 
(TO: « 1) 
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; Adds the first vertex to the polyline at 0,0 
(entmake '((0 . "VERTEX") (100 . "AcDbEntity") (100 . "AcDbVertex"') 
(100 . "AcDb2dVertex") (10 0.0 0.0 0.0) (91 . 0) (70. 0) 
(50 . 0.0))) 
((@ . "VERTEX") (100 . "AcDbEntity") (100 . "AcDbVertex") (100 . "AcDb2dVertex") 
(10 0.0 0.0 0.0) (91 . 0) (70 . 0) (50 . 0.0)) 


; Adds the next vertex to the polyline at 5,5 
(entmake '((0 . "VERTEX") (100 . "AcDbEntity") (100 . "AcDbVertex") 
(100 . "AcDb2dVertex") (10 5.0 5.0 0.0) (91 . 0) (70. 0) 
(50 . 0.0))) 
((@ . "VERTEX") (100 . "AcDbEntity") (100 . "AcDbVertex") (100 . "AcDb2dVertex") 
(10 5.0 5.0 0.0) (91 . 0) (70 . 0) (50 . 0.0)) 


; Adds the next vertex to the polyline at 10,5 
(entmake '((0 . "VERTEX") (100 . "AcDbEntity") (100 . "AcDbVertex") 
(100 . "AcDb2dVertex") (10 10.0 5.0 0.0) (91 . 0) (70. 0) 
(50 . 0.0))) 
((@ . "VERTEX") (100 . "AcDbEntity") (100 . "AcDbVertex") (100 . "AcDb2dVertex") 
(10 10.0 5.0 0.0) (91 . 0) (70 . 0) (50 . 0.0)) 


; Adds the next vertex to the polyline at 10,0 
(entmake '((0 . "VERTEX") (100 . "AcDbEntity") (100 . "AcDbVertex") 
(100 . "AcDb2dVertex") (10 10.0 0.0 0.0) (91 . 0) (70. 0) 
(50 . 0.0))) 
((@ . "VERTEX") (100 . "AcDbEntity") (100 . "AcDbVertex") (100 . "AcDb2dVertex") 
(10 10.0 0.0 0.0) (91 . 0) (70 . 0) (50 . 0.0)) 


; Adds the next vertex to the polyline at 10,0 
(entmake '((@ . "SEQEND") (100 . "AcDbEntity") ) ) 
((0 . "SEQEND") (100 . "AcDbEntity")) 


When you want to modify an old-style polyline, get the polyline object and then use the 
entnext function to step to the first vertex until you get to the seqend object. Using a while 
looping statement is the best way to step through the drawing looking for each vertex of the 
polyline. Continue looping until you encounter a dotted pair with a DXF group code 0 anda 
value of "SEQEND". 

Listing 6.2 is a custom function that demonstrates how to get each of the subobjects of an old- 
style polyline with the while function. 


LISTING 6.2: Listing subobjects of an old-style polyline 


(defun c:ListOSPolyline ( / entityName entityData dxfGroupCode®Q) 
; Set PLINETYPE to © to create an old-style polyline with the PLINE command 
(setq entityName (car (entsel "\nSelect an old-style polyline: "))) 
(setq entityData (entget entityName) ) 
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(if (= (setq dxfGroupCodeO (cdr (assoc © entityData))) "POLYLINE") 
(progn 
(prompt (strcat "\n" dxfGroupCode®) ) 
(setq entityName (entnext entityName) ) 
(setq entityData (entget entityName) ) 


(while (/= (setq dxfGroupCode® (cdr (assoc © entityData))) "SEQEND") 
(prompt (strcat "\n" dxfGroupCoded) ) 
(prompt (strcat "\n" (vl-princ-to-string (assoc 10 entityData)))) 
(setq entityName (entnext entityName) ) 
(setq entityData (entget entityName) ) 


(prompt (strcat "\n" dxfGroupCode®) ) 


) 
(princ) 


) 


The output generated by the custom ListOSPolyline function from Listing 6.2 will be 
similar to the following: 


POLYLINE 

VERTEX 

(10 0.0 0.0 0.0) 
VERTEX 

(10 5.0 5.0 0.0) 
VERTEX 

(10 10.0 5.0 0.0) 
VERTEX 

(10 10.0 0.0 0.0) 
SEQEND 


For more information on the DXF entities polyline, vertex, and seqend, use the AutoCAD 
Help system. Search on the type of object you want to learn more about and be sure to include 
“DXF” as a keyword in the search. For example, the keyword search on the polyline object 
would be “polyline DXF.” 

The following example creates a lightweight polyline that has the coordinate values (0 0), 

(5 5), (10 5), and (10 0) with the entmake function: 


; Create a polyline object drawn along the path (0 0), (5 5), (10 5), and (10 0) 
(entmake '((0 . "LWPOLYLINE") (100 . "AcDbEntity") (100 . "AcDbPolyline") 

(90 . 4) (70 . 1) (43 . 0) (10 © ©) (10 5 5) (10 10 5) (10 10 0))) 
((0 . "LWPOLYLINE") (100 . "AcDbEntity") (100 . "AcDbPolyline") (90 . 4) (70. 1) 
(43 . 0) (10 0 0) (10 5 5) (10 10 5) (10 10 0)) 


The DXF group code 10 in the previous example appears multiple times in the entity data list. 
Each dotted pair with a DXF group code 10 represents a vertex in the polyline, and they appear 
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in the order in which the polyline should be drawn. For more information on the lwpolyline 
DXF entity, search on “Iwpolyline DXF” in the AutoCAD Help system. 

The approaches to updating and querying an old-style and lightweight polyline vary, so you 
will need to handle each type using conditional statements in your programs. You can use the 
getpropertyvalue and setpropertyvalue functions to work with the Vertices property of 
both types of polylines to simplify the code you might need to write. 


Creating and Modifying with Block References 


Block references are often misunderstood by new (and even experienced) AutoLISP developers. 
Blocks are implemented as two separate objects: block definitions and block references. Block 
definitions are nongraphical objects that are stored in a drawing and contain the geometry and 
attribute definitions that make up how the block should appear and behave in the drawing area. 
A block definition can also contain custom properties and dynamic properties. 


UNDERSTANDING BLOCK DEFINITIONS AND BLOCK REFERENCES 


You can think of a block definition much like a cookie recipe. The recipe lists the ingredients that 
make up the cookie and explains how those ingredients are combined for a particular taste, but 
it doesn’t control where the dough will be placed on the baking sheet or the size of the unbaked 
cookies. The placement and amount of the cookie dough on the sheet would be similar to a block 
reference in a drawing. 


A block reference displays an instance, not a copy, of the geometry from a block defini- 
tion; the geometry exists only as part of the block definition, with the exception of attributes. 
Attribute definitions that are part of a block definition are added to a block reference as attri- 
butes unless the attribute definition is defined as a constant attribute. Constant attributes are 
parts of the geometry inherited from a block definition and aren’t part of the block reference. 

When creating a block reference with AutoLISP, as opposed to inserting it with the insert 
command, you are responsible for adding any attributes to the block reference that aren't des- 
ignated as constant within the block definition. Like the old-style polyline, block references use 
the seqend object to designate the end of an insert object. Between the insert and seqend 
objects of a block reference are attrib objects that represent the attribute references that aren't 
set as constant and must be added to a block reference. 

Since attributes must be added to a block reference, it is possible to have a block definition 
that contains attribute definitions and a block reference that points to that block definition with- 
out any attributes. It is also possible to have a block reference that has attributes attached to it 
and a block reference that doesn’t have any attribute definitions. 

The following code adds a block definition named RoomNum (see Figure 6.4) to a drawing 
that has a single attribute with the tag ROOM#: 


; Creates the block definition RoomNum 
(entmake (list (cons © "BLOCK") (cons 2 "roomnum") 
(cons 10 (list 18.0 9.0 0.0)) (cons 70 2))) 


; Creates the rectangle for around the block attribute 
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(entmake (list (cons © "LWPOLYLINE") (cons 100 "AcDbEntity") 
(cons 100 "AcDbPolyline") (cons 90 4) (cons 70 1) 
(cons 43 0) (cons 10 (list 0.0 0.0 0.0)) 
(cons 10 (list 36.0 0.0 0.0)) (cons 10 (list 36.0 18.0 0.0)) 
(cons 10 (list 0.0 18.0 0.0)))) 


; Adds the attribute definition 

(entmake (list (cons © "ATTDEF") (cons 100 "AcDbEntity") 
(cons 100 "AcDbText") (cons 10 (list 18.0 9.0 0.0)) 
(cons 40 9.0) (cons 1 "L000") (cons 7 "Standard") 
(cons 72 1) (cons 11 (list 18.0 9.0 0.0)) 
(cons 100 "AcDbAttributeDefinition") (cons 280 0) 
(cons 3 "ROOM#") (cons 2 "ROOM#") (cons 70 0) 
(cons 74 2) (cons 280 1))) 


; Ends block definition 
(entmake (list (cons © "ENDBLK") ) ) 


Once the block definition is created, you can then use the following code to add a block refer- 
ence to a drawing based on a block named RoomNum: 


; Creates a block reference based on the block definition BlockNumber at 1.0,-0.5 
(entmake '((@ . "INSERT")(100 . "AcDbEntity") (100 . "AcDbBlockReference") 
(66 . 1) (2 . "roomnum") (10 1.0 -0.5 0.0))) 


((@ . "INSERT") (100 . "AcDbEntity") (100 . "AcDbBlockReference") (66 . 1) 
(2 . "RoomNum") (10 1.0 -0.5 0.0)) 


; Creates an attribute reference with the tag ROOM# and adds it to the block 
(entmake '((0 . "ATTRIB") (100 . "AcDbEntity") (100 . "AcDbText") 
(10 0.533834 -0.7 0.0) (40 . 9.0) (1 . "101") (7 . Standard") 
(71 . 0) (72 . 1) (11 1.0 -0.5 0.0) (100 . "AcDbAttribute") 
(280 . ©) (2 . "ROOM#") (70 . ©) (74. 2) (280. 1))) 
(entmake '((0 . "ATTRIB") (100 . "AcDbEntity") (100 . "AcDbText") 
(10 0.533834 -0.7 0.0) (40 . 0.4) (1 . "101") (7 . "Standard") 
(71 . 0) (72 . 1) (11 1.0 -0.5 0.0) (100 . "AcDbAttribute") 
(280 . 0) (2 . "ROOM#") (70 . 0) (74 . 2) (280 . 1))) 


; Adds the end marker for the block reference 
(entmake ' ((0 . "SEQEND") (100 . "AcDbEntity") ) ) 
((0 . "SEQEND") (100 . "AcDbEntity")) 


FIGURE 6.4 


RoomNum block 
reference inserted R O O M 


with AutoLISP 


If you want to extract the values of the attributes attached to a block, you must get the con- 
stant attribute values from the block definition and the nonconstant attribute values that are 
attached as part of the block reference. You use the entnext function to step through each object 
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in a block definition and block reference, collecting information from the reference objects. All 
attribute definitions (attdef) or attribute reference (attrib) objects must be read until the last 
or seqend object is encountered. 

Listing 6.3 shows a custom function that demonstrates how to step through a block reference 
and its block definition with the while function. You must load the custom functions in Listing 6.2 
before executing the code in Listing 6.3. The code in Listing 6.2 and Listing 6.3 can be found in the 
ch06_code_listings.lsp file that is available for download from this book’s website. 


LISTING 6.3: Listing attribute tags and values of a block 


; Lists the attributes attached to a block reference and definition 
(defun c:ListBlockAtts ( / entityName entityData dxfGroupCode@ blkName) 


3 Get a block reference 
(setq entityName (car (entsel "\nSelect a block reference: "))) 
(setq entityData (entget entityName) ) 


; Check to see if the user selected a block reference 
(if (= (setq dxfGroupCodeO (cdr (assoc © entityData))) "INSERT") 
(progn 
; Output information about the block 
(prompt "\n*Block Reference*") 
(prompt (strcat "\n" dxfGroupCode®) ) 
(prompt (strcat "\nBlock name: " (setq blkName (cdr (assoc 2 
entityData))))) 


3 Get the next object in the block, an attrib or seqend 
(setq entityName (entnext entityName) ) 
(setq entityData (entget entityName) ) 


; Step through the attributes in the block reference 
(while (/= (setq dxfGroupCode® (cdr (assoc © entityData))) "SEQEND") 
(prompt (strcat "\n" dxfGroupCoded) ) 
(prompt (strcat "\nTag: " (cdr (assoc 2 entityData)))) 
(prompt (strcat "\nValue: " (cdr (assoc 1 entityData)))) 
(setq entityName (entnext entityName) ) 
(setq entityData (entget entityName) ) 


(prompt (strcat "\n" dxfGroupCode®) ) 
3 Get the block definition 


(setq entityName (cdr (assoc -2 (tblsearch "block" blkName) ) ) ) 
(setq entityData (entget entityName) ) 
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(prompt "\n*Block Definition*") 


3 Get the constant attributes of the block definition 
(while (/= (setq dxfGroupCode® (cdr (assoc © entityData))) nil) 
(if (and (= (setq dxfGroupCode® (cdr (assoc © entityData))) "ATTDEF") 
(> (logand 2 (cdr (assoc 70 entityData))) 0) 


) 
(progn 
(prompt (strcat "\n" dxfGroupCode®) ) 
(prompt (strcat "\nTag: " (assoc 2 entityData) )) 
(prompt (strcat "\nValue: " (assoc 1 entityData))) 
) 


3 Get the next object 
(setq entityName (entnext entityName) ) 
(if entityName 
(setq entityData (entget entityName) ) 
(setq entityData nil) 


) 
(princ) 


) 


Here is an example of the output generated by the custom ListBlockAtts function: 


*Block Reference* 
INSERT 

Block name: RoomNumber 
ATTRIB 

Tag: ROOM# 

Value: 101 

SEQEND 

*Block Definition* 


TIP For more information on the DXF entities insert, attrib, and seqend, use the AutoCAD 
Help system. Search on the type of object you want to learn more about and be sure to include 
“DXF” as a keyword in the search. For example, the keyword search on the insert object would 
be “insert DXF.” 


In addition to using entity data lists to query and modify block references, you can 
use the getpropertyvalue and setpropertyvalue functions. You learned about those 
functions in the “Listing and Changing the Properties of an Object Directly” section earlier 
in this chapter. 
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Extending an Object’s Information 


Each object in a drawing has a pre-established set of properties that define how that object 
should appear or behave. These properties are used to define the size of a circle or the location 
of a line within a drawing. Although you can’t add a new property to an object with AutoLISP, 
you can append custom information to an object. The custom information that you can append 
to an object is known as extended data, or XData. 

XData is structured similar to an entity data list except the values must be within a specific 
range of DXF group codes. Each XData list must contain an application name to identify one 
XData list from another since several XData lists can be attached to an object. After the applica- 
tion name, an XData list can contain any valid values and be of any type of data that AutoLISP 
supports. 

The values in an XData list and what they represent is up to you, the creator of the data. 
Data in an XData list can be used to identify where an object should be placed or which layer it 
should be on, to store information about an external database record that is related to an object, 
or to build relationships between objects in a drawing. The way data is used or enforced is up to 
you as the programmer. 

In addition to XData, graphical and nongraphical objects support what are known as exten- 
sion dictionaries. Extension dictionaries are kind of like record tables that can be attached to an 
object. For example, you could store revision history of a drawing in an extension dictionary 
that is attached to model space, and then populate that information in the drawing’s title block. 
I discuss creating custom dictionaries in Chapter 7. 


Working with XData 

Attaching XData to an object requires you to do some initial planning and perform several 
steps. The following outlines the steps that you must perform in order to attach an XData list 
to an object: 


1. Define and register the application name to use. 
Define the values that will make up the XData list. 
Format the XData list; include a DXF group code -3, application name, and data values. 


Get the entity name and entity data list of an object. 


we WN 


Append the XData list and update the object. 


Prior to appending an XData list, you should check to see if the object already has one with 
the same application name attached to it. If that’s the case, you should replace the current XData 
list with the new list. The following outlines the steps that you must perform in order to modify 
an XData list previously attached to an object: 


1. Define the values that will make up the XData list. 
2. Format the XData list; include a DXF group code -3, application name, and data values. 


3. Get the entity name and entity data list of an object. 
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4. Check for an existing occurrence of an XData list for an object. 
5. Substitute the current XData list attached to an object with the new XData list. 


6. Update the object. 


Defining and Registering an Application Name 
Before you can attach an XData list to an object, you must decide on an application name and 
then register that name with AutoCAD. The application name you choose should be unique to 
avoid conflicts with other XData lists. After an application name has been chosen, you register 
the name with the regapp function. The regapp function adds a new entry to the APPID symbol 
table and returns the name of the application if it is successfully registered. nil is returned if 
the application could not be registered or was already registered in the current drawing. You'll 
learn about symbol tables in Chapter 7. 

The following shows the syntax of the regapp function: 


(regapp appname) 


The appname argument specifies a name for an application you want to register. 
The following example demonstrates how to register an application: 


; Registers the application named MyApp 
(setq appName "MyApp") 
(regapp appName) 


Attaching XData to an Object 

Once you have defined an application name and registered it in a drawing, you can attach an 
XData list to an object within that drawing. An XData list is made up of two lists and has a total 
size limit of 16 KB per object (see the “Managing the Memory Used by XData for an Object” 
sidebar for information). The outer list contains a DXF group code -3 and an inner list that 
contains the application name and dotted pairs that represent the data values to store with the 
object. Each dotted pair contains a DXF group code that defines the type of data the pair repre- 
sents and then the actual value of the pair. 

DXF group codes used for dotted pairs in an XData list must be within the range of 1000 to 
1071. Each DXF group code value in that range represents a different type of data, and you can 
use each DXF group code more than once in an XData list. Table 6.8 lists some of the commonly 
used DXF group codes for XData. 


TABLE 6.8: XData-related DXF group codes 


DXF GROUP CODE DESCRIPTION 


1000 String value 


1001 Application name 
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TABLE 6.8: XData-related DXF group codes (CONTINUED) 
DXF GROUP CODE DESCRIPTION 
1010 3D point 
1040 Real numeric value 
1070 16-bit (unsigned or signed) integer value 
1071 32-bit signed integer value 


The following example is an XData list that contains the application name MyApp and two 
dotted pairs. The first dotted pair is a string (DXF group code 1000) with the value “My custom 
application,” and the second dotted pair is an integer (DXF group code 1070) with a value that 
represents the current date: 


(-3 ("MyApp" (1000 . "My custom application") 
(1070 . (fix (getvar "cdate"))))) 


The following AutoLISP statements were used to create the previous XData list: 


(setq appName "MyApp") 
(regapp "MyApp") 
(setq xdataList (list -3 
(list appName 
(cons 1000 "My custom application") 
(cons 1070 (fix (getvar "cdate"))) 
))) 


Once an XData list has been defined, it can be appended to an entity data list returned by the 
AutoLISP entget function with the append function. I explained how to append lists together in 
Chapter 4. After an XData list is appended to an entity data list, you use the entmod function to 
commit changes to the object and entupd to update the object in the drawing area. I explained 
the entmod and entupd functions earlier in this chapter. 

This exercise shows how to attach an XData list to a circle: 


1. At the AutoCAD Command prompt, type the following and press Enter to register the 
MyApp application: 
(setq appName "MyApp") 
(regapp appName) 

2. Type the following and press Enter to assign the XData list to the xdataList variable: 


(setq xdataList (list -3 
(list appName 
(cons 1000 "My custom application") 
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(cons 1070 (fix (getvar "cdate"))) 
))) 


The XData list assigned to the xdataList variable is as follows: 
(-3 ("MyApp" (1000 . "My custom application") (1070 . 20140302))) 
. Type the following and press Enter to create a new circle: 


(entmake (list (cons © "CIRCLE") (cons 10 (list 2 2 0)) (cons 40 1))) 
(setq circ (entlast)) 


A circle with the center point of 2,2 is created with a radius of 1, and the entity name of 
the new circle is assigned to the circ variable. 


. Type the following and press Enter to get the entity data list of the circle and assign it to 
the entData variable: 


(setq entityData (entget circ)) 
The entity data list of the circle should be similar to the following: 


((-1 . <Entity name: 7ff722905e90>) (© . "CIRCLE") 

(330 . <Entity name: 7ff7229039f0>) (5 . "1E1") (100 . "AcDbEntity") 

(67 . 0) (410 . "Model") (8 . "O") (100 . "AcDbCircle") (10 2.0 2.0 0.0) 
(40 . 1.0) (210 0.0 0.0 1.0)) 


. Type the following and press Enter to append the lists in the entityData and xdataList 
variables: 


(setq entityData (append entityData (list xdataList) )) 


The resulting list is assigned to the entityData variable and should look similar to the 
following: 


((-1 . <Entity name: 7ff722905e50>) (© . "CIRCLE") 

(330 . <Entity name: 7ff7229039f0>) (5 . "1DD")(100 . "AcDbEntity") (67 . 0) 
(410 . "Model") (8 . "O")(100 . "AcDbCircle") (10 2.0 2.0 0.0) (40 . 1.0) 
(210 0.0 0.0 1.0)(-3 ("MyApp" (1000 . "Drill_Hole") (1070 . 20140302)))) 


. Type the following and press Enter to commit the changes to the circle and update the 
circle’s display: 


(entmod entityData) 
(entupd circ) 


The circle object won't look any different after the changes have been committed because 
the XData doesn’t affect the appearance of the object. However, you can now differenti- 
ate this circle from those that might be created with the circle command. This makes 

it much easier to locate and update the radius of the circles that represent a drill hole in 
your drawing. 
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MANAGING THE MEMORY USED BY XDATA FOR AN OBJECT 


Each object in a drawing can have a total of 16 KB worth of XData attached to it. The 16 KB total 
is for all XData attached to an object, and not just for one application. If the limit of XData is close 
and you attach additional XData that exceeds the limit, the XData won't be attached. AutoLISP 
provides two functions to help determine the size of the XData being attached to an object and 
the amount of space already being used by the XData attached to an object. 


The two AutoLISP functions used to manage XData are as follows: 


xdroom—Returns the space available, in bytes, for attaching new XData to an object. The function 
expects an entity name as its single argument. 


xdsize—Returns the size of an XData list in bytes. The function expects a list as its single 
argument. 


You should use these two functions to determine whether XData can be attached to an object. 


Querying and Modifying the XData Attached to an Object 


XData that has been previously attached to an object can be queried and modified by follow- 
ing a process that is similar to the one used to attach XData to an object. The entget function, 
which I discussed earlier, is used to get the entity data list and any XData lists attached to an 
object. By default, the entget function only returns the entity data list for the entity name that 
it is passed. You use the optional appname argument of the entget function to return all of the 
XData lists attached to an object or the one associated with a specific application name. 

For example, the following code returns the entity data list and XData list attached to an 
object with the application name of MyApp. If there is no XData list associated with the applica- 
tion name MyApp, only the entity data list for the object is returned. 


; Return the entity data list and xdata list 
(entget (entlast) '("MyApp") ) 


Using an asterisk instead of an actual application name returns the XData lists for all applica- 
tions attached to an object, as shown here: 


; Return the entity data list and xdata list 
(entget (entlast) '("*!")) 


This exercise shows how to list the XData attached to a dimension with a dimension override: 


1. 
2. 


At the AutoCAD Command prompt, type dli press Enter. 


At the Specify first extension line origin or <select object>: prompt, specify 
a point in the drawing. 


At the Specify second extension line origin: prompt, specify a second point in the 
drawing. 


At the Specify dimension line location or [Mtext/Text/Angle/Horizontal/ 
Vertical/Rotated]: prompt, specify a point in the drawing to place the linear 
dimension. 


EXTENDING AN OBJECT’S INFORMATION 


5. Select the linear dimension that you created, right-click, and then click Properties. 


6. In the Properties palette (Windows) or Properties Inspector (Mac OS), click the Arrow 1 
field under the Lines & Arrows section. Select None from the drop-down list. 


The first arrowhead of the linear dimension is suppressed as a result of a dimension over- 
ride being created. 


7. At the AutoCAD Command prompt, type (assoc -3 (entget (car (entsel "\ 
nSelect object with attached xdata: ")) '("*"))) and press Enter. 


Attaching an XData list to the linear dimension is how AutoCAD handles dimension 
overrides for individual dimensions. Here is what the XData list that was attached to the 
linear dimension as a result of changing the Arrow 1 property in step 6 looks like: 


(-3 ("ACAD" (1000 . "DSTYLE") (1002 . "{") (1070 . 343) (1005 . "2BE") 
(1070 . 173) (1070 . 1) (1070 . 344) (1005 . "O0") (1002 . "}"))) 


NOTE I mentioned earlier that XData doesn’t affect the appearance of an object, and that is 
still true even when used as we did in the previous exercise. XData itself doesn’t affect the 
object, but AutoCAD does look for its own XData and uses it to control the way an object might 
be drawn. If you implement an application with the Autodesk® ObjectARX® application pro- 
gramming interface, you could use ObjectARX and XData to control how an object is drawn 
onscreen. You could also control the way an object looks using object overrules with Managed 
.NET and XData. ObjectARX and Managed .NET are the two advanced programming options 
that Autodesk supports for AutoCAD development. You can learn more about ObjectARX and 
Managed .NET at www. objectarx.com. 


The entget function can be used to determine whether an XData list for a specific applica- 
tion is already attached to an object. If an XData list already exists for an object, you can then 
modify that list. Use the subst function to update or replace one XData list with another. 

This exercise shows how to override the color assigned to dimension and extension lines, and 
restore the arrowhead for the dimension you created in the previous exercise: 


1. At the AutoCAD Command prompt, type the following and press Enter: 
(setq entityName (car (entsel "\nSelect dimension: "))) 


2. Atthe Select dimension: prompt, select the linear dimension created in the previous 
exercise. 


3. At the AutoCAD Command prompt, type the following and press Enter to get the entity 
data list and XData list associated with an application named ACAD: 


(setq entityData (entget entityName '("ACAD"))) 


4. Type the following and press Enter to assign the xdataList variable with the new XData 
list to change the color of the dimension line to ACI 40 and the color of the extension line 
to ACI 200: 


(setq xdataList '(-3 ("ACAD" (1000 . "DSTYLE") (1002 . "{") 
(1070 . 177) (1070 . 200) 
(1070 . 176) (1070 . 40) 
(1002 . "}")))) 
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5. Type the following and press Enter to check whether there is an XData list already 
attached to the object, and if so replace it with the new XData list: 


(if (/= (assoc -3 entityData) nil) 
(setq entityData (subst xdataList (assoc -3 entityData) entityData) ) 
) 


6. Type the following and press Enter to update the linear dimension and commit the 
changes to the drawing: 


(entmod entityData) 
(entupd entityName) 


The colors of the lines in the dimension that are inherited from the dimension style are 
now overridden. This is similar to what happens when you select a dimension, right- 
click, and choose Precision. 


Removing XData from an Object 

XData can be removed from an object when it is no longer needed. You do so by replacing an 
existing XData list with an XData list that contains only an application name. When AutoCAD 
evaluates an XData list with only an application name and no values, it removes the XData list 
from the object. Here is an example of an XData list that can be used to remove the XData asso- 
ciated with the MyApp application: 


(-3 ("MyApp") ) 


The following example removes the XData list associated with an application named ACAD 
from a dimension, which removes all overrides assigned to the dimension: 


(defun c:RemoveDimOverride ( / entityName entityData) 
y y 
(setq entityName (car (entsel "\nSelect dimension to remove overrides: "))) 
(setq entityData (entget entityName '("ACAD"))) 


(if (/= (assoc -3 entityData) nil) 
(setq entityData (subst '(-3 ("ACAD")) (assoc -3 entityData) entityData) ) 


(entmod entityData) 
(entupd entityName) 
(princ) 


) 


Selecting Objects Based on XData 

You can use the XData attached to an object as a way to select or filter out specific objects with 
the ssget function. (I explained how to use the filter argument of the ssget function in the 
“Filtering Selected Objects” section earlier in this chapter.) If you want to filter on the XData 
attached to an object, you use the DXF group code -3 along with the application name from the 
XData list. 
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Here are two examples of the ssget function that use a selection filter to allow for the selec- 
tion of objects that only have XData attached to them with a specific application name: 


3 Selects objects containing xdata and with the application name MyApp. 
(ssget '((-3 ("MyApp")))) 


; Uses implied selection and selects objects with the application name ACAD. 
(ssget "_I" '((-3 ("ACAD")))) 


Exercise: Creating, Querying, and Modifying Objects 


In this section, you will continue to work with the drawplate function that was originally 
introduced in Chapter 2, “Understanding AutoLISP.” Along with working with the drawplate 
function, you will define a new function that will be used to create a bill of materials (BOM) for 
a furniture layout. The key concepts I cover in this exercise are as follows: 


Creating and Modifying Objects without Commands AutoCAD commands make getting 
started with AutoLISP easier, but not all objects can be created from the Command prompt, 
nor can all the properties of an object be modified from the Command prompt. The entmake, 
entget, entmod, and entupd functions give you much greater control over the objects you are 
creating or modifying. 

Creating Selection Sets Requesting objects from the user allows you to create custom func- 
tions that can modify select objects instead of all objects in a drawing. 


Stepping Through Objects in a Selection Set Selection sets can contain one or several 
thousand objects. You must use a looping function, such as repeat or whi Le, to step through 
and get each object in the selection set. 


NOTE Thestepsin this exercise depend on the completion of the steps in the “Exercise: Getting 
Input from the User to Draw the Plate” section of Chapter 5, “Requesting Input and Using 
Conditional and Looping Expressions.” If you didn’t complete the steps, do so now or start 
with the ch06_drawplate. lsp and chO6_utility.lsp sample files available for download 
from www. Sybex. com/go/autocadcustomization. These sample files should be placed in 
the MyCustomF7 les folder within the Documents (or My Documents) folder, or the location 
you are using to store the LSP files. Once the sample files are stored on your system, remove the 
characters ch06_ from the name of each file. 


Revising the Functions in utility.Isp 


The changes to the utility. lsp file replace the use of AutoCAD commands to create objects 
with the entmake function and entity data lists. With these changes, you don’t need to worry 
about the current setting of the osmode and other drafting-related system variables. Creating 
objects with the entmake function also doesn’t display Command prompt strings at the com- 
mand-line window; such strings would need to be suppressed with the cmdecho system variable 
otherwise. Remember, if something happens to go wrong, the fewer system variables you have 
changed, the better off you and your end users are. 
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As you revise the functions, notice how easy it can be to change the underlying functionality 
of your programs when they are divided into several smaller functions. Smaller functions are 
easier not only to change, but to retest if a problem is encountered. 

The following steps explain how to update the various functions in the utility. lsp file: 


1. Open the utility. lsp file in Notepad on Windows or TextEdit on Mac OS. 


2. Inthe text editor area, update the createrectangle, createtext, and createcircle 


functions to match the following: 


3; CreateRectangle function draws a four-sided closed object. 
(defun createrectangle (ptl pt2 pt3 pt4 /) 
(entmake (list (cons © "LWPOLYLINE") (cons 100 "AcDbEntity") 
(cons 100 "AcDbPolyline") (cons 90 4) (cons 70 1) (cons 43 0) 
(cons 10 pt1) (cons 10 pt2) (cons 10 pt3) (cons 10 pt4))) 


; CreateText function creates a single-line text object. 
(defun createtext (insertionPoint alignment height rotation textString / ) 
(entmake (list (cons © "TEXT") (cons 100 "AcDbEntity") (cons 100 "AcDbText") 
(cons 10 insertionPoint) (cons 40 height) (cons 1 textString) 
(cons 50 0.0) (cons 7 "Standard") (cons 72 1) 
(cons 11 insertionPoint) (cons 100 "AcDbText") (cons 73 0))) 


; CreateCircle function draws a circle object. 
(defun createcircle (cenpt rad / ) 
(entmake (list (cons © "circle") (cons 10 cenpt) (cons 40 rad))) 


) 


3. Click File > Save. 


Testing the Changes to the drawplate Function 
Although the changes you made to the utility. lsp file weren't made directly to the drawplate 
function, drawplate uses the createrectangle, createtext, and createcircle functions to 
simplify its code. If the changes were made correctly to the utility. lsp file, you should see no 
differences in the objects created by the drawplate function when compared the one created in 
Chapter 5. 

The following steps explain how to load the LSP files into AutoCAD and then start the 
drawp Late function: 


1. 


Start the appload command. Load the LSP files drawplate.lsp and utility. lsp. If the 
File Loading - Security Concerns message box is displayed, click Load. 


2. At the Command prompt, type drawplate and press Enter. 


Press F2 on Windows or Fn-F2 on Mac OS to expand the command-line window. The cur- 
rent width and height values for the plate are displayed in the command-line history. 


Current width: 5.0000 Current height: 2.7500 
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4. Atthe Specify base point for the plate or [Width/Height]: prompt, type wand 
press Enter. 


5. At the Specify the width of the plate <5.0000>: prompt, type 3 and press Enter. 


6. Atthe Specify base point for the plate or [Width/Height]: prompt, type h and 
press Enter. 


7. Atthe Specify the height of the plate <2.7500>: prompt, type 4 and press Enter. 


8. Atthe Specify base point for the plate or [Width/Height]: prompt, pick a point 
in the drawing area to draw the plate and holes based on the width and height values 
specified. 

9. Atthe Specify label insertion point: prompt, pick a point in the drawing area 
below the plate to place the text label. 

10. Zoom to the extents of the drawing. 


Figure 6.5 shows the completed plate. 


FIGURE 6.5 Plate Size: 5x2.75 


The completed plate 
created using the 
updated utility 
functions 


Defining the New Get-DXF-Value and Set-DXF-Value Utility Functions 


Modifying objects using entity data lists might seem confusing to you—and you aren't alone 
if you feel that way. Entity data lists can even be confusing to some of the most veteran pro- 
grammers at times, as they are not used all the time. Most veteran programmers create utility 
functions that simplify the work. 

In my personal utility library, I have two functions named Get-DXF-Value and Set-DXF-Values 
that can be used to manipulate entity data lists. The Get-DXF-Value function gets the value of a 
dotted pair based on a DXF group code in an entity data list, whereas Set-DXF-VaLues replaces a 
dotted pair or appends a new dotted pair in an entity data list. Set-DXF-Values can be used to 
construct an entity data list as well. The following steps explain how to define the Get-DXF-Value 
and Set-DXF-Values custom functions: 


1. Open the utility. lsp file in Notepad on Windows or TextEdit on Mac OS, if it is not 
already open from the previous steps. 

2. Inthe text editor area, position the cursor after the last expression in the file and press 
Enter twice. Then type the following: 


; Returns the value of the specified DXF group code 
(defun Get-DXF-Value (entityName DXFcode / ) 
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(cdr (assoc DXFcode (entget entityName) ) ) 


; Sets the value of the specified DXF group code for the supplied entity name 
(defun Set-DXF-Value (entityName DXFcode newValue / entityData newPropList 
oldPropList) 
; Get the entity data list for the object 
(setq entityData (entget entityName) ) 


; Create the dotted pair for the new property value 

(setq newPropList (cons DXFcode newValue) ) 

(if (setq oldPropList (assoc DXFcode entityData) ) 
(setq entityData (subst newPropList oldPropList entityData) ) 
(setq entityData (append entityData (list newPropList) ) ) 


; Update the object's entity data list 
(entmod entityData) 


; Refresh the object onscreen 
(entupd entityName) 


; Return the new entity data list 
entityData 
) 


3. Click File > Save. 


Moving Objects to Correct Layers 


Not everyone will agree on the naming conventions, plot styles, and other various aspects of 
layers, but there are a few things drafters can agree on when it comes to layers—that objects 
should do the following: 


¢@ Inherit their properties, for the most part, from the layers in which they are placed 
@ Only be placed on layer 0 when creating blocks 


While I would like to think all the drawings I’ve created are perfect, I know that rush dead- 
lines or other distractions may have affected quality. Maybe the objects were placed on the 
wrong layer or maybe it wasn’t my fault and standards simply changed during the course of a 
project. With AutoLISP, you can identify potential problems in a drawing to let the user know 
about them so they can be fixed, or you can make the changes using AutoLISP. 

In these steps, you create a custom function named furnlayers that is used to identify 
objects by type and value to ensure they are placed on the correct layer. This is achieved using 
selection sets and entity data lists, along with looping and conditional statements. 


1. Create a new LSP file named furntools. lsp with Notepad on Windows or TextEdit on 
Mac OS. 
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2. In the text editor area of the furntools . lsp file, type the following: 


; Moves objects to the correct layers based on a set of established rules 
(defun c:FurnLayers ( / ssFurn cnt entityName entityData entityType) 


; Request the user to select objects 
(setq ssFurn (ssget)) 


; Proceed if ssFurn is not nil 
(if ssFurn 
(progn 
; Set up the default counter 
(setq cnt 0) 


; Step through each block in the selection set 
(while (> (sslength ssFurn) cnt) 
; Get the entity name and entity data of the object 
(setq entityName (ssname ssFurn cnt) 
entityData (entget entityName) 
entityType (strcase (Get-DXF-Value entityName 0))) 


; Conditional statement used to branch based on object type 
(cond 
; If object is a block, continue 
((= entityType "INSERT") 
(cond 
; If the block name starts with RD or CD, 
; then place it on the surfaces layer 
((wematch (strcase (Get-DXF-Value entityName 2)) "RD*,CD*") 
(Set-DXF-Value entityName 8 "surfaces") 
) 
; If the block name starts with PNL, PE, and PX, 
; then place it on the panels layer 
((wematch (strcase (Get-DXF-Value entityName 2)) "PNL*,PE*,PX*") 
(Set-DXF-Value entityName 8 "panels") 
) 
; If the block name starts with SF, 
3; then place it on the panels layer 
((wematch (strcase (Get-DXF-Value entityName 2)) "SF*") 
(Set-DXF-Value entityName 8 "storage") 


; If object is a dimension, continue 

((= entityType "DIMENSION") 
; Place the dimension on the dimensions layer 
(Set-DXF-Value entityName 8 "dimensions") 
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3; Increment the counter by 1 
(setq cnt (1+ cnt)) 


) 
(princ) 


) 


Creating a Basic Block Attribute Extraction Program 


The designs you create take time and, based on the industry you are in, are often what is used to 
earn income for your company or even save money. Based on the types of objects in a drawing, 
you can step through a drawing and get attribute information from blocks or even geometric 
values such as lengths and radii of circles. You can use the objects in a drawing to estimate the 
potential cost of a project or even provide information to manufacturing. 

In these steps, you create a custom function named furnbom that is used to get the values of 
two attributes (part and Label) attached to a block. The attribute values are added to a list and 
then sorted using the acad_strlsort function. Once sorted, the list is then parsed and quanti- 
fied into a new list, which is used to create the a BOM table made up of lines and text. 


1. Open the furntools. lsp file with Notepad on Windows or TextEdit on Mac OS, if it is 
not already open. 


2. Inthe text editor area of the furntools.1sp file, type the following: 


3; extAttsFurnBOM - Extracts, sorts, and quanitifies the attribute information 
(defun extAttsFurnBOM (ssFurn / cnt preVal part label furnList) 

; Set up the default counter 

(setq cnt 0) 


; Step through each block in the selection set 
(while (> (sslength ssFurn) cnt) 
; Get the entity name and entity data of the block 
(setq entityName (entnext (ssname ssFurn cnt))) 
(setq entityData (entget entityName) ) 


3; Step through the objects that appear after 
; the block reference, looking for attributes 
(while (/= (cdr (assoc © entityData)) "SEQEND") 
; Check to see which if the attribute tag is PART or TAG 
(cond 
((= (strcease (Get-DXF-Value entityName 2)) "PART") 
(setq part (Get-DXF-Value entityName 1)) 
) 
((= (strcase (Get-DXF-Value entityName 2)) "LABEL") 
(setq label (Get-DXF-Value entityName 1) ) 
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; Get the next entity (attribute or sequence end) 
(setq entityName (entnext entityName) ) 
(setq entityData (entget entityName) ) 

) 


; Add the part and label values to the list 
(setq furnList (append furnList 
(list (strcat label "\t" part)) 
)) 


3; Increment the counter by 1 
(setq cnt (1+ cnt)) 


; Sort the list of parts and labels 
(setq furnListSorted (acad_strlsort furnList) ) 


; Reset and set variables that will be used in the looping statement 
(setq cnt 0 


furnList nil preVal nil) 


; Quantify the list of parts and labels 
; Step through each value in the sorted list 
(foreach val furnListSorted 
; Check to see if the previous value is the same as the current value 
(if (or (= preVal val) (= preVal nil)) 
(progn 
; Increment the counter by 1 
(setq cnt (1+ cnt)) 


; Values weren't the same, so record the quanity 
(progn 


; Add the quanity and the value (part/label) to the final list 
(setq furnList 


(append furnList 
(list 
(list (itoa cnt) 
(substr preVal 1 (vl-string-search "\t" preVal) ) 
(substr preVal (+ (vl-string-search "\t" preVal) 2))) 
))) 


; Reset the counter 
(setq cnt 1) 
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; keep the previous value for comparison 
(setq preVal val) 


; Add the quanity and the value (part/label) to the final list 
(setq furnList (append furnList 
(list (list (itoa cnt) 
(substr preVal 1 (vl-string-search "\t" preVal) ) 
(substr preVal (+ (vl-string-search "\t" preVal) 2))) 
))) 


; Return the quantified and control character-delimited "\t" 
furnList 


; Create the bill of materials table/grid 
(defun tableFurnBOM (qtyList insPt / colWidths tableWidth rowHeight 
tableHeight headers textHeight 
col insText item insTextCol bottomRow) 


; Define the sizes of the table and grid 
(setq colWidths (list © 15 45 50) 
tableWidth 0 
row 1 
rowHeight 4 
tableHeight 0 
textHeight (- rowHeight 1)) 


; Get the table width by adding all column widths 
(foreach colWidth colWidths 
(setq tableWidth (+ colWidth tableWidth) ) 


; Define the standard table headers 

(setq headers (list "QTY" "LABELS" "PARTS") ) 

; Create the top of the table 

(entmake (list (cons 0 "LINE") (cons 10 insPt) 


(cons 11 (polar insPt © tableWidth) ))) 


; Get the bottom of the header row 
(setq bottomRow (polar insPt (* -1 (/ PI 2)) rowHeight) ) 


; Add headers to the table 
(rowValuesFurnBOM headers bottomRow colWidths) 


33 (setq tableHeight (+ tableHeight rowHeight) ) 
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; Step through each item in the list 

(foreach item qtyList 
(setq row (1+ row)) 
(setq bottomRow (polar insPt (* -1 (/ PI 2)) (* row rowHeight) )) 
(rowValuesFurnBOM item bottomRow colWidths) 


; Create the vertical lines for each column 

(setq colWidthTotal 0) 

(foreach colWidth colWidths 
; Calculate the placement of each vertical line (left to right) 
(setq colWidthTotal (+ colWidth colWidthTotal) ) 
(setq colBasePt (polar insPt © colWidthTotal) ) 


; Draw the vertical line 
(entmake (list (cons 0 "LINE") (cons 10 colBasePt) 
(cons 11 (polar colBasePt (* -1 (/ PI 2)) 
(distance insPt bottomRow) ) ))) 


(defun rowValuesFurnBOM (itemsList bottomRow colWidths / tableWidth) 
; Calculate the insertion point for the header text 
(setq rowText (list (+ 0.5 (nth 0 bottomRow) ) 
(+ 0.5 (nth 1 bottomRow) ) 
(nth 2 bottomRow) ) 
tableWidth 0 


; Get the table width by adding all column widths 
(foreach colWidth colWidths 
(setq tableWidth (+ colWidth tableWidth) ) 


; Lay out the text in each row 

(setq col 0 colWidthTotal 0) 

(foreach item itemsList 
; Calculate the placement of each text object (left to right) 
(setq colWidthTotal (+ (nth col colWidths) colWidthTotal) ) 
(setq insTextCol (polar rowText © colWidthTotal) ) 


; Draw the single-line text object 
(entmake (list (cons © "TEXT") (cons 100 "AcDbEntity") 
(cons 100 "AcDbText") (cons 10 insTextCol) 
(cons 40 textHeight) (cons 1 item) (cons 50 0.0) 
(cons 7 "Standard") (cons 11 insTextCol) 
(cons 100 "AcDbText") )) 
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; Create the top of the table 
(entmake (list (cons © "LINE") (cons 10 bottomRow) 
(cons 11 (polar bottomRow © tableWidth) ))) 


; Increment the counter 
(setq col (1+ col)) 


; Extracts, aggregates, and counts attributes from the furniture blocks 
(defun c:FurnBOM ( / ssFurn eaList) 


; Get the blocks to extract 
(setq ssFurn (ssget '((0 . "INSERT")))) 


; Use the extAttsFurnBOM to extract and quantify the attributes in the blocks 
; If ssFurn is not nil proceed 
(if ssFurn 
(progn 
; Extract and quantify the parts in the drawing 
(setq eaList (extAttsFurnBOM ssFurn) ) 


; Create the layer named BOM or set it as current 
(createlayer "BOM" 8) 


; Prompt the user for the point to create the BOM 
(setq insPt (getpoint "\nSpecify upper-left corner of BOM: ")) 


3; Start the function that creates the table grid 
(tableFurnBOM eaList insPt) 


) 
(princ) 


) 
3. Click File > Save. 


Using the Functions in the furntools.Isp File 

The functions you added to furntools. lsp leverage some of those defined in utility. 1sp. 
These functions allow you to change the layers of objects in a drawing and extract information 
from the objects in a drawing as well. More specifically, they let you work with blocks that rep- 
resent an office furniture layout. 

Although you might be working in a civil engineering- or mechanical design-—related field, 
these concepts can and do apply to the work you do—just in different ways. Instead of extracting 
information from a furniture block, you could get and set information in a title block, a callout, 
or even an elevation marker. Making sure a hatch is placed on the correct layers, along with 
dimensions, can improve the quality of output for the designs your company creates. 
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NOTE The following steps require a drawing file named Ch06_Office_Layout. dwg. If you 
didn’t download the sample files earlier, download them now from www. sybex.com/go/ 
autocadcustomization. These sample files should be placed in the MyCustomFi les folder 
within the Documents (or My Documents) folder. 


The following steps explain how to use the furnlayers function that is in the 
furntools. lsp file: 


1. Open Cho6_Office_Layout.dwg. Figure 6.6 shows the office layout that is in the drawing. 
FIGURE 6.6 


Office furniture 
layout 


2. Start the appload command. Load the LSP files furntools.1lsp and utility. lsp. If the 
File Loading - Security Concerns message box is displayed, click Load. 


3. At the Command prompt, type furnlayers and press Enter. 
4. Atthe Select objects: prompt, select all the objects in the drawing and press Enter. 


The objects in the drawing are placed on the correct layers. Earlier the objects were placed 
on layer 0 and had a color of white (or black) based on the background color of the draw- 
ing area. 


The following steps explain how to use the furnbom function that is in the 
furntools. lsp file: 


1. Open the Cho6_Office_Layout. dwg if it is not open from the previous steps. 


2. Load the furntools. lsp and utility. lsp files if you opened the drawing 
in step 1. 


3. At the Command prompt, type furnbom and press Enter. 


4. Atthe Select objects: prompt, select all the objects in the drawing. Don’t press 
Enter yet. 
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Notice that the dimension objects aren't highlighted. This is because the ssget function 
is only allowing block references (insert object types) to be selected as a result of the fil- 
ter being applied. 


5. Press Enter to end the object selection. 


6. Atthe Specify upper-left corner of BOM: prompt, specify a point to the right of the 
furniture layout in the drawing. 


The BOM that represents the furniture blocks is placed in a table grid, as shown in 
Figure 6.7. 


FIGURE 6.7 


Bill of materials 4 
generated from 4 
the office furniture 4 


layout 


Creating and Modifying 
Nongraphical Objects 


Nongraphical objects represent the block definitions, named styles, and other objects that 

are stored in a drawing but aren’t present in model space or one of the named layouts. These 
objects can and typically do affect the display of graphical objects placed in model space or a 
named layout, though. While model space and named layouts are typically not thought of as 
nongraphical objects, they are. Model space is a special block definition, whereas a layout is an 
object that is based on a plot configuration—commonly called a page setup—with a reference 
to a block definition. 

A drawing file can contain two types of nongraphical objects: symbol tables and named 
dictionaries. Symbol tables represent the original named objects that were available in the 
AutoCAD® R12 release and earlier ones. Support for named dictionaries was added with 
AutoCAD R13 to handle new and custom objects without the need for a new drawing file format. 
In this chapter, you will learn to create, manage, and use symbol table and dictionary entries. 


Working with Symbol Tables 


Symbol tables are the oldest form of nongraphical objects used in drawing files and have been 
unchanged since AutoCAD R12. Although the features that use symbol tables have changed 
since AutoCAD R12, the additional information that those features use in later releases is 
attached as either XData or an extension dictionary on an entry or the symbol table. 


ED Real World Scenario 
THE HIDDEN VALUE OF NONGRAPHICAL OBJECTS 


Have you opened a drawing from a client to find what seems like a spaghetti mess of layers, 
linetypes, and text styles that just don’t work well with your standards? Maybe the Standard 
text style in the client’s drawings uses a fixed height and different font than your company 
uses, which would affect the way your blocks and annotation might look like in the drawing. 
Using the AutoLISP® programming language, you can create or change nongraphical objects 
stored in symbol tables or dictionaries so they align with your company’s standards. Aligning 
the standards in the drawings received from a client ensure that the objects you create and 
those in the drawings plot with a consistent appearance. 
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For example, the transparency level and description of a layer is attached as XData to a layer 
table entry, and both layer states and filters are attached as extension dictionaries to the layer 
table. I covered XData in Chapter 6, “Creating and Modifying Graphical Objects” and will 
discuss dictionaries in the section “Working with Dictionaries” later in this chapter. 

Table 7.1 lists the symbol-table names that are supported in all drawing files created 
with AutoCAD R12 and later. 


TABLE 7.1: Symbol-table names 
TABLE NAME DESCRIPTION 
appid Registered applications 
block Block definitions 
dimstyle Dimension styles 
layer Layers 
ltype Linetypes 
style Text styles 
ucs User coordinate systems 
view Named views 
vport Viewports 


Accessing and Stepping through Symbol Tables 


AutoLISP provides three functions that allow you to access the entries of a symbol table or 
determine if a specific entry exists in a symbol table. The tblnext function returns either the first 
or next entry in a specified symbol table. The tblnext function is similar to the entnext function 
that I discussed in Chapter 6. 

The following shows the syntax of the tblnext function: 


(tblnext sym_table [next]) 


Its arguments are as follows: 


sym_table The sym_table argument is a string used to specify the symbol table which you 
want to query, and it must be one of the values listed in the first column of Table 7.1. 


next The next argument is optional, and specifies whether you want to get the first entry of 
a symbol table or the next symbol-table entry after the previous entry that was returned. Use 
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a value of T to return the first value. When no argument or nil is provided, an entity data list 


of the next symbol table entry is returned. 


The following example code shows the tblnext function and the resulting list of layer names 


in a drawing: 


; Lists the layers in the drawing 

(defun c:listlayers ( / entityData) 
(prompt "\nLayers in this drawing:") 
(setq entityData (tblnext "Layer" T)) 


(while entityData 
(prompt (strcat "\n" (cdr (assoc 2 entityData)))) 
(setq entityData (tblnext "Layer") ) 

) 

(princ) 


) 


Layers in this drawing: 
(0) 

Labels 

Panels 

Surfaces 

Storage 

Defpoints 

Dimensions 

BOM 


To check for the existence of or get the entity data list of an entry in a symbol table, you can 
use the tblsearch function. If the name of the entry in the specified table exists, an entity data 
list is returned for the entry; otherwise, nil is returned. The tblobjname function can also be 
used to check for the existence of a symbol table entry, but unlike the tblsearch function, 
tblobjname returns the entity name (ename) of the entry if it is found; otherwise, it returns nil. 

The following shows the syntax of the tblsearch and tblobjname functions: 


(tblsearch sym_table entry [next]) 
(tblobjname sym_table entry) 


The arguments are as follows: 


sym_table The sym_table argument is a string that represents the symbol table you want to 
query, and it must be one of the values in the first column of Table 7.1. 


entry The entry argument is a string that represents the entry you want to check for in the 
symbol table specified by the sym_table argument. 


next The next argument is optional and represents whether the next call to tblnext uses the 
results of the tblsearch function to determine its starting entry. Use a value of T to not affect 


the next call of the tblnext function in the current drawing. When no argument or nil is 
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provided, the tblnext function bases the entity it returns on the position of the entry pro- 
vided by the entry argument. 


Here are some examples of the tblobjname and tblsearch functions, and their results: 


; Get the entity data list for layer 0 
(tblsearch "Layer" "09") 
((@ . "LAYER") (2. "@") (70 . 0) (62 . 7) (6 . "Continuous") ) 


; Get the entity data list for the layer BOM 
(tblsearch "Layer" "BOM") 
nil 


; Get the entity name of layer 0 
(tblobjname "layer" "0") 
<Entity name: 7ff6cde08900> 


; Get the entity name of the BOM layer 
(tblobjname "layer" "BOM") 
nil 


; Check for the existence of the BOM layer 
(if (tblobjname "Layer" "BOM") 
(alert "BOM layer already exists in the current drawing.") 


Adding and Modifying Entries in a Symbol Table 

Most symbol table entries are inherited from the drawing template that was used to create a 
drawing file or are created as a result of inserting a block into a drawing. A drawing template 
should contain most of the layers, linetypes, and other nongraphical objects you might want 
to use in your drawing, but you can use AutoLISP to create and modify any additional system 
table entries you might need. The methods you use to create and modify nongraphical objects 
are the same as those for graphical objects (which I explained in Chapter 6). 

The symbol table entries you create or modify should follow your company’s established 
CAD standards or those of the industry in which you work. Modifying existing table entries 
should be done with care, because the changes you make could have an adverse effect on exist- 
ing objects in a drawing. For example, changing the height of a text style could affect dimen- 
sions and tables in your drawing. 
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©) Real World Scenario 
AN OUNCE OF PREVENTION 


It is 3:00 p.m., and your boss just let you know that a set of drawings needs to be sent out by 
6:00 p.m. for an initial bid. You output all of the drawings, only to discover that objects in 
some of the drawings weren't placed on the correct layers and text styles don’t use the correct 
fonts. Everyone decided to take a half day today because they have been working frantically 
for the past two weeks on this project. Getting the project across the finish line now rests on 
your shoulders. The drawings need to be sent out for the initial bid, but their current state is 
less than ideal for a first impression to the new client. 


What to do? 


Take a deep breath and channel your inner AutoLISP to create a program that can be executed 
in each drawing to change the text styles to use the correct fonts—one problem down. Now, 
on to the layer issues. 


Using AutoLISP, you can verify whether the correct layer exists and, if not, create the new layer. 
With selection filters that you learned about in Chapter 6, you can select and move objects to 
their appropriate layers based on object type or current property values. 


Now that the drawings have been fixed, you output the revised drawings with minutes to spare. 
This battle is won, but the war for CAD excellence is not over yet. Custom programs created 
with AutoLISP can help you to enforce CAD standards in your office. Using the programs you 
create, a drafter can focus more on the elements of a design and less on switching to the cor- 
rect layer and style before adding new objects. 


ADDING AN ENTRY 


You can add a new style table entry using the appropriate AutoCAD command with the command 
function. For example, you can use the - layer command to create a new layer, -block to create a 
new block, or -linetype to create or load a linetype pattern. 

As you learned in Chapter 6, you can use the command function with AutoCAD commands, 
but I recommend using the entmake or entmakex function to create new objects instead. Creating 
new objects with entity data lists gives you more control over the object that you create, but it 
requires you to learn the DXF group codes and values that each object expects. For informa- 
tion on the entmake and entmakex functions, see the “Adding Objects to a Drawing” section in 
Chapter 6. 
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TIP You can use the tblobjname and entget functions to return the entity data list of an 
existing symbol table entry that you want to reproduce using AutoLISP. For example, (entget 
(tblobjname "ltype" "center")) returns the entity data list for the Center linetype if it is 
loaded in the current drawing. 


This next code example attempts to create a new layer named Centerlines with the linetype 
Center: 
(entmake (list (cons © "LAYER") (cons 100 "AcDbSymbolTableRecord") 
(cons 100 "AcDbLayerTableRecord") (cons 2 "Centerlines") 
(cons 70 0) (cons 62 3) (cons 6 "Center"))) 
Error: Undefined line type Center in LayerTableRecord Centernil 


An error message and nil is returned if the Center linetype doesn’t exist in the drawing 
prior to creating the layer. Before you create symbol table entries, you must make sure that all 
of the objects they depend on are present in the drawing. For example, a linetype must exist in 
a drawing before a layer that uses the linetype can be created. The same is true of dimension 
styles; the text style and linetypes that a dimension style might reference must exist in the draw- 
ing before you create the dimension style. 

This example checks for the Center linetype and, if it doesn’t exist, the linetype is created 
using the entmake function: 


(if (= (tblsearch "Ltype" "center") nil) 
(entmake (list (cons 0 "LTYPE")(cons 100 "AcDbSymbolTableRecord") 
(cons 100 "AcDbLinetypeTableRecord") (cons 2 "CENTER") (cons 70 0) 
(cons 3 "Center 22 2 2222 2 2- LL kL") (cons 72 65) 


(cons 73 4) (cons 40 2.0) (cons 49 1.25) (cons 74 0) (cons 49 -0.25) 
(cons 74 0) (cons 49 0.25) (cons 74 0) (cons 49 -0.25) (cons 74 0)) 


) 
((@ . "LTYPE") (100 . "AcDbSymbolTableRecord") (100 . "AcDbLinetypeTableRecord") 


(2 . "CENTER") (70 . @) (3 . "Center _ 2 2 2 2 8 Lee _———") 
(72 . 65) (73 . 4) (40 . 2.0) (49 . 1.25) (74 . 0) (49 . -0.25) (74 . 0) 
(49 . 0.25) (74 . 0) (49 . -0.25) (74 . 0)) 


Using the previous example, you can ensure that the Center linetype exists in the draw- 
ing before you try to create the Centerlines layer. Now if you try to create the Centerlines layer 
with the following example, the new layer is created since the Center linetype is defined in the 
drawing. 


(entmake (list (cons © "LAYER") (cons 100 "AcDbSymbolTableRecord") 

(cons 100 "AcDbLayerTableRecord") (cons 2 "Centerlines") 

(cons 70 0) (cons 62 3) (cons 6 "Center"))) 
((@ . "LAYER") (100 . "AcDbSymbolTableRecord") (100 . "AcDbLayerTableRecord") 
(2 . "Centerlines") (70 . 0) (62 . 3) (6 . "Center")) 


Before creating a new symbol table entry with entmake or entmakex, you should verify that it 
doesn’t already exist. If the symbol table entry already exists, entmake or entmakex will return 
nil. I also recommend checking the name of the symbol table entry you are trying to add with 
the snvalid function. The snvalid function verifies that the name doesn’t contain any invalid 
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characters and follows the naming rules based on the current value of the extnames system vari- 
able. For more information on the extnames system variable, see the AutoCAD Help system. 
The following shows the syntax of the snvalid function: 


(snvalid name [flag]) 


Here are its arguments: 


name The name argument is a string that represents the name of the symbol table entry you 
want to verify. 


flag The flag argument is an optional integer that determines whether the symbol table 
entry name can contain a vertical bar. 0 indicates that a vertical bar is not allowed, whereas 
1 indicates that the vertical bar is a valid character as long as it isn’t the first character in the 
entry name. 


Here are some examples of using the snvalid function and the values that are returned: 
(snvalid "Centerlines") 

T 

(snvalid "Centerlines?") 

nil 

(snvalid "Detail|Centerlines" 0) 


nil 


(snvalid " Detail|Centerlines " 1) 
T 


MODIFYING AND RENAMING AN ENTRY 


Symbol table entries can be modified and renamed using the same techniques that you learned 
in Chapter 6 for modifying graphical objects. You can use the AutoLISP functions listed in 
Table 7.2 to modify symbol table entries. 


TABLE 7.2: Functions that can be used to modify symbol table entries 
FUNCTION NAME DESCRIPTION 
entget Returns the entity data list for an object 
entmod Commits an entity data list to an object 
dumpallproperties Outputs the property names and their current values for an object 
getpropertyvalue Returns an object’s property value 
jispropertyreadonly Determines whether an object’s property is read-only 


setpropertyvalue Sets an object’s property value 
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When modifying symbol table entries, you should understand that not all entries can be 
renamed or modified. For example, you can modify layer 0 but you can’t rename the layer. The 
layers that you create, with the exception of those in an attached external reference, can be mod- 
ified and renamed. Table 7.3 lists the symbol table entries that you can’t rename and/or modify. 


TABLE 7.3: Symbol table entry name and modification limits 
TABLE NAME ENTRY NAME DESCRIPTION 
appid Nothing specific Entries can’t be renamed, but they can be removed. 
block *model_space and Model space and paper space block definitions can’t be renamed 


*paper_space or removed. Drawings can have more than one paper space block; 


these additional blocks have a numeric suffix starting at 1. 


dimstyle standard Can be modified but not renamed or removed. 
layer 0 Can be modified but not renamed or removed. 
ltype continuous Can't be modified, renamed, or removed. 

style standard Can be modified but not renamed or removed. 
ucs *active Can be modified but not renamed or removed. 
vport *active Can be modified but not renamed or removed. 


Here’s an example that shows how to rename a layer and its current color by using its entity 
data list. The name of a symbol table entry is designated with the dotted pair that has the DXF 
group code 2 key element. 


; Get the layer named "BOM" 
(setq entityName (tblobjname "layer" "BOM") ) 


; Get the entity data for the layer 
(setq entityData (entget entityName) ) 


; Rename the layer from "BOM" to "Bill of Materials" 
(setq entityData (subst (cons 2 "Bill of Materials") 
(assoc 2 entityData) entityData) ) 


; Change the layers color to 5 
(setq entityData (subst (cons 62 5) (assoc 62 entityData) entityData) ) 


; Update the layer 
(entmod entityData) 
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The following example renames the layer “Bill of Materials” back to “BOM” and changes the 
layer color to 8 with the setpropertyvalue function: 


; Get the layer named "Bill of Materials" 
(setq entityName (tblobjname "layer" "Bill of Materials") ) 


; Rename the layer from "Bill of Materials" to "BOM" 
(setpropertyvalue entityName "name" "BOM") 


; Change the layer's color to 8 
(setpropertyvalue entityName "color" 8) 


USING AN OBJECT 


After a symbol table entry is created, you can use that entry in a number of ways based on the 
type of object it represents. The most common is to set it as current using a system variable 
before creating a new object so that the new object inherits the properties of the symbol table 
entry when possible. For example, you can use the clayer system variable to set the active layer 
in the drawing, or use celtype to indicate the linetype that new objects should inherit. You 
should refer to the setvar command and the AutoCAD Help system to identify the system vari- 
ables your AutoCAD release supports and the properties they might affect. 

In addition to system variables, you can change the name of a symbol table entry assigned to 
an object using entity data lists with the entmod function or directly with the getpropertyvalue 
and setpropertyvalue functions. If you created a new named view, you can use the setview func- 
tion to set the view current in a viewport. For more information on the setview function, see the 
AutoCAD Help system. 


REMOVING AN ENTRY THAT Is NO LONGER NEEDED 


Since the same techniques can be used to create and modify both graphical and symbol table 
entries, you might think that removing a symbol table entry and a graphical object would also 
be the same in AutoLISP. The entdel function is used to remove graphical objects, but it can- 
not be used to remove symbol table entries. This is one of the very few times that you can’t use 
“classic” AutoLISP to do something. Instead of using a specific AutoLISP function, you must use 
the command function with the -purge command to remove a symbol-table object. 

You can use the tblobjname and tblsearch functions to determine whether a specific symbol 
table entry exists in a drawing, and then use the -purge command to remove it. If the symbol 
table entry doesn’t exist or cannot be removed because it is being used, the -purge command 
will end gracefully without any significant error messages that require user interaction to dis- 
miss. Here’s an example of how to remove a block named roomlabel from a drawing with the 
-purge command: 


(command "._-purge" "_b" "roomlabel" "_n") 


NOTE On Windows only, you can use the AutoLISP vla-delete function after loading the 
AutoCAD ActiveX/COM interface with the vl-load-com function. I discuss the basics of using 
ActiveX with AutoLISP in Chapter 12, “Working with ActiveX/COM Libraries (Windows only).” 
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Creating and Modifying Block Definitions 
Although some symbol table entries can seem complex at first, blocks are probably at the top 
of the list when it comes to complexity. When you initially create a block entry, the block entry 
contains no graphical objects. You add graphical objects to a block entry similar to how you add 
objects to a drawing with the entmake or entmakex function. 

A block definition has a beginning (header) of the block object type and an ending sequence 
of the endblk object type. The beginning sequence tells AutoCAD that a block definition is being 
created along with the following information (at minimum): 


@ Block name (DXF group code 2) 
@ Block-type flags as a bitcode (DXF group code 70) 
@ Base point (DXF group code 10) 


The block-type flag is typically set to a value of 0 (which indicates that the block doesn’t 
contain attribute definitions or that all of the attribute definitions are constant) or to a value of 
2 (which indicates that the block contains nonconstant attributes). Once the block definition is 
started, use the entmake or entmakex function to add objects to the block definition. You can’t 
add an attribute reference (attrib) object to a block definition. Instead, add attribute defini- 
tion (attdef) objects to a block definition. These are used to define the attribute references that 
should be added to a block reference when it is inserted into model space or paper space with 
the insert command. 

Here’s a basic representation of the entity data lists that you need to create to define a block 
without any attributes or graphical objects. Passing the entity data lists to the entmake function 
will create an empty block. 


3; Start block definition 
((0 . "BLOCK") (2 . "some_block_name") (10 0.0 0.0 0.0) (70 . 0)) 


; Objects here with entmake 


; End block definition 
((@ . "ENDBLK")) 


If you want to revise the content of a block definition (also known as redefining a block), 
there are a couple of different processes. Choose the process you need based on how the block 
definition should be revised: 


Updating or Removing Objects Step through the objects of a block definition when you 
need to change the properties of or remove an existing object in a block definition. Get the 
entity name of the block definition with the tblobjname function and step through the block 
definition with the entnext function. Change the objects in the block definition as you would 
those in a model space or paper space. Use the entdel function to remove objects from a 
block definition. 


Adding Objects You must re-create the block definition by going through the process used 
to create the block. That is, to start the block definition, add the objects and then add the end 
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block-definition marker. If you don’t want to re-create all of the objects as part of the block 
definition, you can create a block reference in the drawing and explode it. Once it’s exploded, 
you can add the new objects you want to add to the block in model space and then use the 
-block command to redefine the block definition. 


NOTE On Windows only, you can use AutoLISP vla-add<object> functions to add objects 
directly to an existing block definition. I discuss the basics of using ActiveX with AutoLISP in 
Chapter 12. 


In the following exercise, you'll create a new block definition and layer. The new block defini- 
tion is named circ and it contains a single circle object with a base point of 0,0. The new layer is 
named hardware and has a color value of 3 (green). 


1. Create a new drawing. 


2. At the AutoCAD Command prompt, type the following and then press Enter to start the 
block definition for the circ block: 


(entmake (List (cons © "block") (cons 2 "circ") 


(cons 10 (list 0.0 0.0 0.0))(cons 70 0))) 


3. Type the following and press Enter to add the circle at 0,0 with a radius of 2. The 
circle is placed on layer 0 so that it inherits the properties of the layer on which the 
block is placed. 


(entmake (list (cons 0 "circle") (cons 10 (list 0.0 0.0 0.0)) 
(cons 40 2)(cons 8 "0"))) 
4. Type the following and press Enter to end the circ block definition: 
(entmake (list (cons 0 "endblk"))) 


5. Type the following and press Enter to create the layer named hardware with a color of 3 
and a linetype of Continuous: 


(entmake (list (cons © "layer") (cons 100 "AcDbSymbolTableRecord") 
(cons 100 "AcDbLayerTableRecord") (cons 2 "hardware") 
(cons 70 0) (cons 62 3) (cons 6 "Continuous") )) 
6. Type the following and press Enter to set the hardware layer as current: 


(setvar "clayer" "hardware") 


7. Type insert and press Enter to display the Insert (Windows) or Insert Block (Mac OS) 
dialog box. 


8. When the Insert dialog box opens, click the Name drop-down list and select circ. 


9. Deselect all the check boxes under the Insert Point, Scale, and Rotation sections. Click OK 
(Windows) or Insert (Mac OS) to insert the block into the drawing. 


210 |CHAPTER7 CREATING AND MODIFYING NONGRAPHICAL OBJECTS 


10. Zoom to the extents of the drawing. 
11. Select the new object in the drawing. Right-click and choose Properties. 


12. In the Properties palette (Windows) or Properties Inspector (Mac OS), you should notice 
that the object is a block named circ and that it has been placed on the hardware layer. 


Working with Dictionaries 


Dictionaries are used to store custom information and objects in a drawing and can be thought 
of as symbol tables 2.0. Dictionaries were introduced with AutoCAD R13 as a way to introduce 
new symbol tables like objects without the need to change the drawing file format with each 
release. Although there is only one type of dictionary in a drawing, dictionaries can be stored in 
two different ways: per drawing or per object. 

The main dictionary of a drawing contains nested dictionaries that store multileader and 
table styles, and even the layouts used to output a drawing. Dictionaries attached to an object 
are known as extension dictionaries. Extension dictionaries are similar to XData but allow you to 
attach more information to a single object. AutoCAD uses extension dictionaries attached to the 
layer symbol table to store the information used for layer states and filters. 

Custom dictionaries are great for storing custom program settings so that they persist across 
drawing sessions. You might also use a custom dictionary as a way to store drawing revision 
history or project information that can be used to track a drawing and populate a title block. In 
this section, you'll learn how to access, create, query, and modify information stored in 
a dictionary. 


Accessing and Stepping through Dictionaries 


The dictionary-related AutoLISP functions are similar to those used when working with symbol 
tables. Before you can access the entries in a dictionary, you must first get a dictionary. The 
namedobjdict function returns the entity name of the drawing’s named-object dictionary. This 
is the main dictionary that contains all the dictionaries that aren’t attached to an object as an 
extension dictionary. The namedobjdict function doesn’t require any arguments. 

Once you have the entity name of the named object dictionary, use the entget function to get 
an entity data list that contains the key entries and entity names for each dictionary. Each entry 
in the named object dictionary is represented by two dotted pairs. The first dotted pair repre- 
sents the unique name of a dictionary and DXF group code 3. The second dotted pair contains 
the entity name for the dictionary and DXF group code 350. 

Here’s an example of an entity data list for a named object dictionary: 


((-1 . <Entity name: 7ff6646038c0>) (© . "DICTIONARY") (330 . <Entity name: 0>) 
(5 . "C") (100 . "AcDbDictionary") (280 . 0) (281 . 1) (3 . "ACAD_COLOR") 

(350 . <Entity name: 7ff664603c30>) (3 . "ACAD_GROUP") 

(350 . <Entity name: 7ff6646038d0>) (3 . "ACAD_VISUALSTYLE") 

(350 . <Entity name: 7ff6646039a0>) (3 . "ACAD _MATERIAL") 

(350 . <Entity name: 7ff664603c20>) ) 


The third dictionary entry in the example entity data list is (3 . "ACAD_VISUALSTYLE") (350 
. <Entity name: 7ff6646039a0>), and this entry allows you to access the visual styles of the cur- 
rent drawing. The code in Listing 7.1 returns the entity name for a ACAD_VISUALSTYLE dictionary. 
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LISTING 7.1: Custom function that returns the Visual Styles dictionary 


; Custom function that returns the entity name of a specific dictionary entry 
(defun GetDictionaryByKeyEntry (dictionaryEntity dKeyEntry / 
entityData dkKeyEntry dEntityName cnt) 
(setq entityData (entget dictionaryEntity) ) 


(setq dEntityName nil) 


(setq cnt 0) 
(while (and (= dEntityName nil)(< cnt (length entityData))) 
(if (and (= (car (nth cnt entityData)) 3) 
(= (cdr (nth cnt entityData)) dKeyEntry)) 
(progn 
(setq dEntityName (cdr (nth (1+ cnt) entityData))) 


) 
(setq cnt (1+ cnt)) 
) 
dEntityName 
) 


; Example of using the custom function 
(GetDictionaryByKeyEntry (namedobjdict) "ACAD_VISUALSTYLE") 


After you have the entity name for the dictionary you want to work with, you can use the 
dictnext function to return either the first or next item attached to the dictionary. The dictnext 
function is similar to the tblnext function, which I discussed earlier in this chapter. 

The following shows the syntax of the dictnext function: 


(dictnext ename [next]) 


Its arguments are as follows: 


ename The ename argument is an entity name that represents the dictionary you want to step 
through. 


next The next argument is optional, and it specifies whether you want to get the first entry 
of a dictionary or the entry after the one that was returned by the last use of the dictnext 
function. Use a value of T to return the entity name of the first entry in the dictionary. When 
no argument or nil is provided, the entity name of the next entry is returned. 


The following example code uses the AutoLISP dictnext function and the 
GetDictionaryByKeyEntry function in Listing 7.1 to step through and list the names of each visual 
style in the drawing. The code is followed by an output listing from one of my drawings. 


; Lists the visual styles in the drawing 

(defun c:listvisualstyles ( / entityData dictionaryName) 
(setq dictionaryName (GetDictionaryByKeyEntry (namedobjdict) 
"ACAD_VISUALSTYLE") ) 
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(prompt "\nVisual styles in this drawing:") 
(setq entityData (dictnext dictionaryName T)) 


(while entityData 
(prompt (strcat "\n" (cdr (assoc 2 entityData)))) 
(setq entityData (dictnext dictionaryName) ) 

) 

(princ) 


) 


Visual styles in this drawing: 
2dWireframe 
Basic 

Brighten 
ColorChange 
Conceptual 

Dim 

EdgeColorOff 
Facepattern 

Flat 
FlatwithEdges 
Gouraud 
GouraudwithEdges 
Hidden 

JitterOff 
Linepattern 
OverhangOff 
Realistic 

Shaded 

Shaded with edges 
Shades of Gray 
Sketchy 

Thicken 
Wireframe 

X-Ray 


If you know (or want to check for the existence of) a key entry in a dictionary, you 
can use the dictsearch function. If the name of the key entry in the dictionary exists, 
the entity data list of the key entry is returned; otherwise, nil is returned. Here’s an 
example of using the dictsearch function to get the entity data list associated with the 
ACAD_TABLESTYLE dictionary: 


(setq entityData (dictsearch (namedobjdict) "ACAD_TABLESTYLE") ) 
((-1 . <Entity name: 7ff664603ce0>) (© . "DICTIONARY") (5 . "86") 
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(102 . "{ACAD_REACTORS") (330 . <Entity name: 7ff6646038c0>) 
(102 . "}") (330 . <Entity name: 7ff6646038c0>) 

(100 . "AcDbDictionary") (280 . 0) (281 . 1) (3 . "Standard") 
(350 . <Entity name: 7ff664603cf0>) ) 


Once you have the entity data list for the dictionary, you can use the assoc function to 
get the dictionary’s entity name, which is associated with the DXF group code —1. After 
you get the entity name for the dictionary, you can then pass it to the dictsearch func- 
tion to locate a specific key entry in the dictionary. The following shows how to get the 
Standard table style entry from the entity data list of the ACAD_TABLESTYLE dictionary: 


(setq entityNameTS (cdr (assoc -1 entityData) )) 

(setq entityDataTS (dictsearch entityNameTS "STANDARD") ) 

((-1 . <Entity name: 7ff664603cf0>) (© . "TABLESTYLE") (5 . "87") 
(102 . "{ACAD_XDICTIONARY") (360 . <Entity name: 7ff664605340>) 
(102 . "}") (102 . "{ACAD_REACTORS") 

(330 . <Entity name: 7ff664603ce0>) (102 . "}") 

(330 . <Entity name: 7ff664603ce0>) (100 . "AcDbTableStyle") 

(280 . 0) (3 . "Standard") 


(68 . 0) (279 . -2) (289 . 1) (69 . 0)) 
Here’s the syntax of the dictsearch function: 
(dictsearch ename entry) 


Its arguments are as follows: 


ename The ename argument is an entity name that represents the dictionary you want to 
query to check for the existence of the key entry specified by the entry argument. 


entry The entry argument is a string that represents the entry you want to check for in the 
dictionary specified by the ename argument. 


NOTE Youcan use the layoutlist function to get a list of the named layouts in the current 
drawing. For more information on this function, see the AutoCAD Help system. 


Creating a Custom Dictionary 


As I mentioned earlier, one of the benefits of dictionaries is that you can store custom informa- 
tion or settings related to the programs you create in a drawing. Before a custom dictionary 
can be used and entries added to it, it must first be created. The entmakex function, not entmake, 
is used to create a dictionary. Once created, the new dictionary can be attached to either the 
named object dictionary or an object as an extension dictionary. You attach the new dictionary 
to the drawing’s named object dictionary with the dictadd function. 
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The following shows the syntax of the dictadd function: 
(dictadd ename key_entry dictionary) 


Its arguments are as follows: 


ename The ename argument is an entity name that represents the object (named or object’s 
extension dictionary). The dictionary that is specified by the dictionary argument is attached 
to the object. 


key_entry The key_entry argument is a string that represents the unique key entry name 
that you want to associate with the dictionary that is specified by the dictionary argument. 


dictionary The dictionary argument is an entity name that represents the dictionary that 
you want to attach to the entity name specified by the ename argument. 


Here’s an example that creates a dictionary named MY_CUSTOM_DICTIONARY and adds it to the 
named object dictionary: 


; Create dictionary object 
(setq entityName (entmakex (list (cons 0 "DICTIONARY") 
(cons 100 "AcDbDictionary") ) )) 


; Add the dictionary to the named object dictionary 
(setq newdictionary (dictadd (namedobjdict) "MY_CUSTOM_DICTIONARY" 
entityName) ) 


In addition to adding a dictionary to the named object dictionary that is returned by the 
namedobjdict function, you can create an extension dictionary on a graphical object. The exten- 
sion dictionary is similar to the named object dictionary of a drawing, and it can hold nested 
dictionaries of extended records. I discuss extended records (Xrecords) in the next section. 

This example adds an extension dictionary to the last object in a drawing: 


; Creates a new dictionary 
(setq dictionary 
(entmakex (list (cons © "DICTIONARY") (cons 100 "AcDbDictionary") ) )) 


; Entity Data list of the extension dictionary 
(setq exDictionary (list (cons 102 "{ACAD_XDICTIONARY") 
(cons 360 dictionary) (cons 102 "}"))) 


; Attach the extension dictionary to the last object 
(setq entityData (append (entget (entlast)) exDictionary) ) 
(entmod entityData) 


Once the extension dictionary is attached to the object, you can use the DXF group code 360 
to get the entity name of the extension dictionary. With the entity name, you can then add dic- 
tionaries or Xrecords to the object’s extension dictionary. 
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This example gets the entity name of the extension dictionary attached to the last object in 
the drawing: 


(cdr (assoc 360 (entget (entlast)))) 


nilis returned if no extension dictionary has been added to the object. 


Storing Information in a Custom Dictionary 


After a custom dictionary has been created, you add entries to a custom dictionary using the 
dictadd function. Entries of a custom dictionary are often of the extended record (also known as 
an Xrecord) object type. An Xrecord is similar to XData and can be attached to an object, but it 
contains DXF group codes that are in the same range as graphical objects. You create an Xrecord 
with the entmakex function before attaching it to the dictionary. 

The following code creates an Xrecord and attaches it to MY_CUSTOM_DICTIONARY, which can be 
created using the example from the previous section, with the XR1 key entry. The Xrecord con- 
tains a string (DXF group code 1), a coordinate value (DXF group code 10), and an integer (DXF 
group code 71). 


; Add the Xrecord to the dictionary 
(dictadd newdictionary "XR1" 
(entmakex (list (cons © "XRECORD") (cons 100 "AcDbXrecord") 
(cons 1 "Custom string") (cons 10 (list 5.0 5.0 0.0)) 
(cons 71 11)))) 


If you need to make a change to the data contained in an Xrecord that has been attached to a 
dictionary, use the dictsearch function to get the entry’s entity data list. The dotted pairs in the 
entity data list can be replaced with the assoc function as needed, just like updating a graphical 
object or symbol table entry. Entries can also be renamed from a custom dictionary; you'll learn 
how to rename and remove entries in the next section. 


Managing Custom Dictionaries and Entries 
After a dictionary or Xrecord object has been created and attached, you can change its key 
entry or remove it as needed. Although you can freely rename and remove the dictionaries and 
Xrecords you create, those created by AutoCAD can also be renamed and removed. I recom- 
mend being cautious about renaming or removing those created by AutoCAD, because doing so 
could cause problems. Not all dictionaries and objects attached to a dictionary can be removed 
since they may be referenced by other objects. When a dictionary is successfully renamed, the 
new name of the dictionary is returned (or nil is returned when the dictionary couldn't be 
renamed). Similarly, the ename of a dictionary is returned when a dictionary is removed or nil 
is returned if it couldn’t be removed. 

You can use the dictrename function to change the current key entry to a new key entry 
value. The dictremove function can be used to remove a dictionary or an entry in a dictionary. 

The following shows the syntax of the dictrename function: 


(dictrename ename old_key_entry new_key_entry) 
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Its arguments are as follows: 


ename The ename argument is an entity name that represents the dictionary or entry whose 
current key entry name (old_key_entry argument) you want to change to the new key entry 
name (new_key_entry argument). 


old_key_entry The old_key_entry argument is a string that represents the current unique 
key entry name associated with the dictionary or entry that is specified by the ename 
argument. 


new_key_entry The new_key_entry argument is a string that represents the new unique key 
entry name that should replace the key entry specified by the old_key_entry argument. 


The following shows the syntax of the dictremove function: 
(dictremove ename key_entry) 


Its arguments are as follows: 


ename The ename argument is an entity name that represents the dictionary that has the dic- 
tionary or entry you want to remove. 


key_entry The key_entry argument is a string that represents the unique key entry name of 
the dictionary or entry you want to remove from the object specified by the ename argument. 


Here are examples that rename and remove a custom dictionary: 


; Renames the key entry of a dictionary 
(dictrename (namedobjdict) "MY_CUSTOM_DICTIONARY" "MY_DICTIONARY") 


; Removes the custom dictionary with the key entry "MY_DICTIONARY" 
(dictremove (namedobjdict) "MY_DICTIONARY") 


Exercise: Creating and Incrementing Room Labels 


In this section, you will create several new functions that will be used to define and insert 
room-label blocks into a drawing. Room labels are used to identify areas in architectural draw- 
ings, but the same concept can be applied to callouts in mechanical drawings. 

As you insert a room label block with the custom program, a counter increments by 1 so you 
can place the next room label without having to manually enter a new value. Before the 
room-labeling program ends, the last calculated value is stored in a custom dictionary so it can 
be retrieved the next time the program is started (instead of using global variables). The key 
concepts covered in this exercise are as follows: 


Creating and Modifying Symbol Table Entries Symbol table entries in a drawing can 
affect the display of graphical objects in a drawing. Each drawing that you create contains a 
set number of symbol tables you can access using AutoLISP. You can then create or manipu- 
late any of the entries that are in one of the symbol tables. 


Using Symbol Table Entries As new objects are created, you can assign the names of sym- 
bol table entries to various properties of an object so that it inherits the symbol table entries’ 
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properties. You can change the value associated with the DXF group code 8 of an object to 
move the object between layers, or even change the value associated to the DXF group code 2 
of a block reference to change which block definition it inherits its geometry from. 


Creating and Storing Information in a Custom Dictionary Values assigned to variables in 
a drawing are temporary, but you can use custom dictionaries to persist values across draw- 
ing sessions. The values stored in a drawing can then be recovered by your programs after 
the drawing is closed and reopened, similar to how system variables work. 


NOTE Thestepsin this exercise depend on the completion of the steps in the “Exercise: Creating, 
Querying, and Modifying Objects” section of Chapter 6. If you didn’t complete these exercises, do 
so now or start with the ch07_building_plan. dwg and ch07_utility.1lsp sample files available 
for download from www. sybex.com/go/autocadcustomization. These sample files should 
be placed in the MyCustomFiles folder within the Documents (or My Documents) folder, or the 
location you are using to store the LSP files. Once the files are stored on your system, remove 
ch07_ from the name of the LSP file. 


Revising the createlayer Function in utility.Isp 


The changes you will make to the utility. lsp file update the createlayer function so that the 
function checks to see if the layer already exists before it creates the layer, instead of the current 
behavior of automatically creating/modifying the layer. With these changes, the function checks 
for the existence of the layer with the tblobjname function and creates the new layer (if it doesn’t 
already exist) using the entmake function. 

The following steps explain how to update the various functions in the utility. lsp file: 


1. Open the utility.1sp file in Notepad on Windows or TextEdit on Mac OS. 


2. Inthe text editor area, update the createrlayer function to match the code that 
follows: 


; CreateLayer function creates a layer and 
; expects two argument values. 
(defun createlayer (name color / ) 
(if (= (tblobjname "layer" name) nil) 
(entmake (list (cons © "LAYER") (cons 100 "AcDbSymbolTableRecord") 
(cons 100 "AcDbLayerTableRecord") (cons 2 name) 
(cons 70 0) (cons 62 color) (cons 6 "Continuous") )) 


3. Click File > Save. 


Creating the Room Label Block Definition 


Creating separate drawing files that your custom programs depend on has its advantages 
and disadvantages. The advantage of creating a separate drawing file is that you can use the 
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AutoCAD user interface to create the block file. However, AutoCAD will need to know where 
the drawing file is stored so the custom program can use the file. The advantage of creating the 
block definition through code is that no separate drawing file needs to be maintained, making it 
easier to share your custom application with your clients or subcontractors. 

In these steps, you create a custom function named roomlabel_createblkdef that will be used 
to create the block definition for the room label block if it doesn’t already exist in the drawing. 


1. Create a new LSP file named roomlabel. lsp using Notepad (on Windows) or TextEdit (on 
Mac OS). 


2. In the text editor area of the roomlabel. lsp file, type the following: 


; Creates the block definition roomlabel 


(defun RoomLabel_CreateBlkDef ( / ) 
(setvar "clayer" "9") 


; Start block definition 
(entmake (list (cons 0 "BLOCK") (cons 2 "roomlabel") 
(cons 10 (list 18.0 9.0 0.0)) (cons 70 2))) 


; Create the rectangle for around the block attribute 
(createrectangle (list 0.0 0.0 0.0) (list 36.0 0.0 0.0) 
(list 36.0 18.0 0.0) (list 0.0 18.0 0.0)) 


; Add the attribute definition 

(entmake (list (cons © "ATTDEF") (cons 100 "AcDbEntity") 
(cons 8 "Plan_RoomLabel_Anno") (cons 100 "AcDbText") 
(cons 10 (list 18.0 9.0 0.0)) (cons 40 9.0) (cons 1 "LOQO") 
(cons 7 "Standard") (cons 72 1) (cons 11 (list 18.0 9.0 

0.0)) 

(cons 100 "AcDbAttributeDefinition") (cons 280 0) 
(cons 3 "ROOM#") (cons 2 "ROOM#") (cons 70 ©) (cons 74 2) 
(cons 280 1))) 


; End block definition 
(entmake (list (cons © "ENDBLK"') )) 
(princ) 


) 


3. Click File > Save. The block definition that will be created when the code is executed is 
shown in Figure 7.1. 


FIGURE 7.1 


RoomLabel block O O M 
definition 
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Inserting a Block Reference Based on the Room Label 
Block Definition 


Once the block definition has been created and added to the block symbol table, it can be 
inserted into the drawing with the insert command or even used to define a block reference 
with the entmake function. 

In the next exercise steps, you will create three custom functions: addattrefs, changeattvalue, 
and roomlabel_insertblkref. The addattrefs function is a helper function used to add attribute 
references to a block reference based on the attribute definitions that are part of a block definition. 
The changeattvalue function allows you to revise the insertion point and value of an attribute ref- 
erence attached to a block reference based on the attribute’s tag. The roomlabel_insertblkref func- 
tion creates a block reference based on the RoomLabel block definition that we created with the 
roomlabel_createblkdef function. 


1. Open the roomlabel. lsp file with Notepad (Windows) or TextEdit (Mac OS), if it is not 
already open. 


2. In the text editor area of the roomlabel. lsp file, type the following: 


; Adds attribute references from a block definition to a block reference 
(defun AddAttRefs (blockName / entityName entityData) 

3 Gets the entity name for the block definition 

(setq entityName (tblobjname "block" blockName) ) 


3; Steps through the block definition 
(while entityName 
3 Gets the entity data list for the entity 
(setq entityData (entget entityName) ) 


; Checks to see if the entity is an attribute definition 
(if (= (strease (cdr (assoc © entityData))) "ATTDEF") 
3; Checks to see if the attribute definition is constant or not 
(if (/= (logand 2 (cdr (assoc 70 entityData) ))) 
(progn 
3; Converts the object type from ATTDEF to ATTRIB 
(setq entityData (subst (cons 0 "ATTRIB") 
(assoc © entityData) entityData) ) 
(setq entityData (subst (cons 100 "AcDbAttribute") 
(cons 100 "AcDbAttributeDefinition") 
entityData) ) 


; Removes the Handle, entity name, and owner from 
; the entity data list 
(foreach dxfGroupCode (list -1 5 330 3) 3 67 210 
(setq list_begin (reverse (cdr 
(member (assoc dxfGroupCode entityData) 
(reverse entityData) )))) 
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(setq list_end (cdr (member (assoc dxfGroupCode entityData) 
entityData) ) ) 
(setq entityData (append list_begin list_end) ) 


; Creates the new attribute reference based on 
; the attribute definition 


(entmake entityData) 
) 


; Gets the next block in the block definition 
(setq entityName (entnext entityName) ) 

) 

(princ) 


) 


; Changes the value of an attribute reference in a block reference 
(defun ChangeAttValue (blkRefEntityName insPt attTag newValue / entityName 
entityData) 
; Gets the first object in a block reference 
(setq entityName (entnext blkRefEntityName) ) 


; Steps through the block reference 

(while entityName 
3 Gets the entity data list for the entity 
(setq entityData (entget entityName) ) 


; Checks to see if the entity is an attribute definition 
(if (= (strease (cdr (assoc © entityData))) "ATTRIB") 
3 Checks to see if the attribute definition is constant or not 
(if (= (strcase (cdr (assoc 2 entityData))) (strcase attTag) ) 
(progn 
3 Update the attribute value 
(entmod (setq entityData (subst (cons 1 newValue) 
(assoc 1 entityData) entityData) ) ) 


; Changes the position of the attribute 
(if (/= insPt nil) 
(progn 
(entmod (setq entityData (subst (cons 10 insPt) 
(assoc 10 entityData) 
entityData) )) 
(entmod (setq entityData (subst (cons 11 insPt) 
(assoc 11 entityData) 
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entityData) ) ) 


(entupd entityName) 


; Gets the next block in the block reference 
(setq entityName (entnext entityName) ) 

) 

(princ) 


) 


; Creates the block definition roomlabel 
(defun RoomLabel_InsertBlkRef (insPoint labelValue / blkLayer) 
(setq blkLayer "Plan_RoomLabel_Anno") 


; Creates the "Plan_RoomLabel_Anno" layer 
(createlayer blkLayer 150) 


; Checks to see if the block definition exists in the drawing; 

; if not, the block definition is added 

(if (= (tblobjname "block" "roomlabel") nil) 
(RoomLabel_CreateBlkDef) 


; Creates the block reference 

(entmake (list (cons © "INSERT") (cons 8 blkLayer) 
(cons 100 "AcDbEntity") (cons 100 "AcDbBlockReference") 
(cons 66 1) (cons 2 "roomlabel") (cons 10 insPoint) )) 


; Adds the attribute references to the block reference 
(AddAttRefs "roomlabel") 


; Ends block reference 
(entmake (list (cons © "SEQEND") (cons 100 "AcDbEntity") )) 


; Changes the attribute value of the "ROOM#" 
(ChangeAttValue (entlast) insPoint "ROOM#" LabelValue) 


(princ) 


) 


3. Click File > Save. 
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Prompting the User for an Insertion Point and Room Number 


Now that you have defined the functions for creating the block definition and inserting the 
block reference into a drawing, you need a function that prompts the user for input. The 
roomlabel function will allow the user to specify a point in the drawing, provide a new room 
number, or provide a new prefix. The roomlabel function uses the default number of 101 and a 
prefix of L. 

As you use the roomlabel function, it creates and uses a custom dictionary named 
My_Custom_Program_Settings with an entry RoomLabel. If the RoomLabel entry 
exists, it writes the number and prefix of the last room label that you placed. Closing and 
reopening the drawing results in the program picking up where you left off. 

In these steps, you'll create the custom function roomlabel that uses all the functions 
that you defined in this exercise to place a RoomLabel block each time you specify a 
point in the drawing: 


1. Open the roomlabel. sp file with Notepad (Windows) or TextEdit (Mac OS), if it is 
not already open. 


2. Inthe text editor area of the roomlabel. lsp file, type the following: 


; Prompts the user for an insertion point and room number 
(defun c:RoomLabel ( / lastNumber lastPrefix entityName roomLabelEntry val 
newNumber newPrefix roomLabelEntry mySettings) 
; Gets the custom dictionary "My_Custom_Program_Settings" if it exists 
(setq mySettings (cdr (assoc -1 
(dictsearch (namedobjdict) "My_Custom_Program_Settings") )) ) 


; Defines initial values 
(setq lastNumber 101 lastPrefix "L") 


; If the dictionary exists, gets the last used room number 
(if (/= mySettings nil) 
(progn 
; Gets the last room number from the "RoomLabel" key entry 
(if (/= (setq roomLabelEntry (dictsearch mySettings "RoomLabel")) nil) 
(progn 
; Gets the previously stored number and prefix 
(setq lastNumber (cdr (assoc 71 roomLabelEntry) ) ) 
(setq lastPrefix (cdr (assoc 1 roomLabelEntry) ) ) 


) 

) 
) 
(progn 

; Creates the new "My_Custom_Program_Settings" 

(setq entityName (entmakex (list (cons © "DICTIONARY") 

(cons 100 "AcDbDictionary") ) )) 
(setq mySettings 
(dictadd (namedobjdict) "My_Custom_Program_Settings" 
entityName) ) 
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; If no "RoomLabel" entry exists, creates one based on the defaults 
(if (= roomLabelEntry nil) 
(progn 
(dictadd mySettings "RoomLabel" 
(entmakex (list (cons © "XRECORD") (cons 100 "AcDbXrecord") 
(cons 1 lastPrefix) (cons 71 LastNumber) ) )) 


; Displays current values 
(prompt (strcat "\nPrefix: " LlastPrefix "\tNumber: " (itoa LastNumber) ) ) 
(initget "Number Prefix") 


; Prompts the user for an insertion point 
(while (setq val (getpoint (strcat "\nSpecify point for room label (" 
lastPrefix (itoa lastNumber) 
") or change [Number/Prefix]: "))) 
; Checks to see if the user provided a keyword or insertion point 


; User provided a string 
(cond 
((= (type val) 'STR) 
(if (= (strcase val) "NUMBER") 
3; User specified to enter a number 
(progn 
(setq newNumber (getint 
(strcat "\nEnter new room number <" (itoa lastNumber) ">: "))) 
(if newNumber (setq LastNumber newNumber) ) 
) 
; User specified to enter a new prefix 
(progn 
(setq newPrefix (getstring 
(strcat "\nEnter new room number prefix <" LastPrefix ">: "))) 
(if newPrefix (setq lastPrefix newPrefix) ) 


) 


; User provided a point: insert room label block based on values 
((= (type val) 'LIST) 
(RoomLabel_InsertBlkRef val (strcat lastPrefix (itoa lastNumber) ) ) 


; Increments number by 1 
(setq lastNumber (1+ lastNumber) ) 
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; Removes and re-creates the "RoomLabel" dictionary entry 
(dictremove mySettings "RoomLabel") 


(dictadd mySettings "RoomLabel" 
(entmakex (list (cons © "XRECORD") (cons 100 "AcDbXrecord"') 
(cons 1 lastPrefix) (cons 71 LastNumber) ))) 


; Displays current values 


(prompt (strcat "\nPrefix: " LlastPrefix "\tNumber: " (itoa LastNumber) ) ) 
(initget "Number Prefix") 


) 
(princ) 


) 


3. Click File > Save. 


Adding Room Labels to a Drawing 


The roomlabel. lsp file contains the main roomlabel function, but some of the helper functions 
you defined in roomlabel. lsp use functions defined in the utility. lsp file. 


NOTE The following steps require a drawing file named ch07_building_plan. dwg. If you didn’t 
download the sample files previously, download them now from this book’s web page. Place 
these sample files in the MyCustomFi les folder within the Documents (or My Documents) folder. 


The following steps explain how to use the roomlabel function that is in the room 
label. lsp file: 


1. Open Cho7_Building_Plan.dwg. Figure 7.2 shows the plan drawing of the office 
building. 


FIGURE 7.2 
Plan view of the 
office building 


2. 


EXERCISE: CREATING AND INCREMENTING ROOM LABELS| 225 


Start the appload command. Load the LSP files roomlabel. sp and utility. sp. If the File 
Loading - Security Concerns message box is displayed, click Load. 


3. At the Command prompt, type roomlabel then press Enter. 


FIGURE 7.3 
Inserted 


At the Specify point for room label (L101) or change [Number/Prefix]: 
prompt, specify a point inside the room in the lower-left corner of the building. 


The room-label definition block, Plan_RoomLabel_Anno layer, and My_Custom_ 
Program_Settings custom dictionary are created the first time the roomlabel function is 
used. The RoomLabel block definition should look like Figure 7.3 when inserted into 
the drawing. 


L101 
RoomLabel block 


5. 


At the Specify point for room label (L101) or change [Number/Prefix]: prompt, type n 
and press Enter. 


6. At the Enter new room number <102>: prompt, type 105 and press Enter. 


At the Specify point for room label (L105) or change [Number/Prefix]: prompt, type 
p and press Enter. 


At the Enter new room number prefix <L>: prompt, type R and press Enter. 


9. Atthe Specify point for room label (R105) or change [Number/Prefix]: prompt, 


14. 


specify a point in the large open area in the middle of the building. 


. Press Enter to end roomlabel. 
. Save the drawing with the name RoomLabel Test.dwg, and then close the file. 
. Open RoomLabel Test.dwg, and load the roomlabel. sp and utility. lsp files. 


. Start the roomlabel function. Press F2 on Windows or Fn-F2 on Mac OS. Notice the cur- 


rent values being used are 106 for the number and a prefix of R, which are the values you 
used before closing the drawing. 


Add additional room labels and close the drawing when done. 


Working with the Operating 
System and External Files 


The AutoLISP® programming language can be used to reach beyond the boundaries of the 
Autodesk® AutoCAD® application window and objects in the current open drawing. Using 
AutoLISP, you can access settings managed by the operating system and installed applications 
on Windows or by the application-level settings of AutoCAD on both Windows and Mac OS. 
You can access operating system- and application-level settings from the Windows Registry. On 
Mac OS, you can access application-level settings for AutoCAD from the Plist (property list) files. 
Along with accessing operating system and application settings, you can read and write 
ASCII (plain text) files that are stored on a local or network drive. You can use content in an 
ASCII file to populate project information in a title block or as a means to export information 
from a drawing. Exported information can be used to create or update objects in a drawing 
or to generate a quote based on the values of attributes in blocks placed within a drawing. In 
addition to reading and writing ASCII files, you can use AutoLISP to manage and get general 
information about the files and directories on a local or network drive. In this chapter, you'll 
learn to persist values between AutoCAD sessions, write to and read from external files, and 
work with files in the operating system. 


Storing Information in the Windows Registry or a 
Plist File 


AutoCAD stores information and setting values using many different methods. Some are 
proprietary; others are industry standard. Most setting values are stored as part of the drawing 
using system variables, extended data, or custom dictionaries. Those settings that aren’t stored 
with the drawing are, for the most part, stored with the AutoCAD user profile. 
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ED Real World Scenario 
SENDING INFORMATION DOWNSTREAM 


After much praise about the furniture layout that you did for the new office space, your boss has 
come back from lunch with a local furniture reseller who has a new request. During his lunch 
meeting, the reseller mentioned that they could create a pricing quote from the BOM information 
if it was provided in a comma-separated values (CSV) file. 


You begin to ponder the situation, and then the lightbulb goes on. The AutoLISP program you wrote 
has already tabulated the BOM information in a list. Using AutoLISP, you can write the values from 
that tabulated list to a CSV file. Once again, AutoLISP helped you step up your game and get the 
job done more efficiently. 


The AutoCAD user profile on Windows is maintained in the Windows Registry, while Plist 
files are used on Mac OS. Both provide the same fundamental functionality, with one difference: 
Plist files are application specific and are not centralized like the Windows Registry. 

I discussed how to work with system variables using AutoLISP in Chapter 2, “Understanding 
AutoLISP.” Extended data (Xdata) was explored in Chapter 6, “Creating and Modifying 
Graphical Objects,” and Chapter 7, “Creating and Modifying Nongraphical Objects,” covered 
working with custom dictionaries. 


Creating and Querying Entries 

On Windows, you can create and query values in the Windows Registry. The values that you 
can access in the Registry aren’t just related to AutoCAD but are those managed by Windows 
and other installed applications. If you are developing custom programs on Mac OS, you can 
access the information stored in the AutoCAD-related Plist files. 

You can work with two main areas (known as keys) in the Windows Registry: HKEY_LOCAL_ 
MACHINE and HKEY_CURRENT_USER. On Mac OS, the Plist files that correspond to these Windows 
Registry keys are HKLM.plist and HKCU. plist, respectively. 

Values in HKEY_LOCAL_MACHINE are typically set by an application installer and changing 
them might require administrator rights, which AutoLISP can’t obtain. You should treat the 
values of HKEY_LOCAL_MACHINE as read-only since most users won't have the rights to change 
the values in this key. You can create and query values in the HKEY_CURRENT_USER area without 
any limitations, and this is the preferred area for adding new values when you want your pro- 
grams to have access between AutoCAD sessions. 

You can add values under the Software/AutoCAD key, but I recommend adding any custom 
values to a key that is specific to your company under the Software key. This will ensure that 
you don’t accidentally overwrite or remove values used by another program. 

The vl-registry-write function is used to create a key and assign a value to a key. It is also 
used to verify whether a key or value can be modified. The value you assign can be of the string 
or integer data type. The vl-registry-read function is used to access a value assigned to a key. 
If the key and value exist, the data returned can be a string, integer, or list (which represents a 
binary value). If the key or value doesn’t exist, nil is returned. 
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The following shows the syntax of the vl-registry-write and vl-registry-read 
functions: 


(vl-registry-write key [value_name data]) 
(vl-registry-read key [value_name]) 


The arguments are as follows: 


key The key argument is a string that specifies the key in the Windows Registry or Plist file 
that you want to access. 


value_name The value_name argument is an optional string that specifies the name of the 
value under the key specified by the key argument. If the value_name and data arguments 
aren't provided, T is returned if the key supports read/write access or nil if read-only access 
is permitted. Use "" to access the value (Default) under a key. 


data The data argument is an optional string or integer that is used to specify the data to 
assign to the value under the key specified by the value_name argument. A string data type 
when working with the Registry is known as a REG_SZ type, and an integer can be either a 
REG_DWORD (32-bit integer) or REG_QWORD (64-bit integer). Use "" to specify an empty string. 


Here are some examples of writing and reading values to and from the Windows Registry or 
a Plist file: 


; Checks to see if the key can be modified 
(vl-registry-write "HKEY_CURRENT_USER\\Software\\CompanyABC123") 
T 


; Creates the entry Integer under CompanyABC123 and assigns it 123 
(vl-registry-write "HKEY_CURRENT_USER\\Software\\CompanyABC123" "Integer" 123) 
123 


; Creates the entry String under CompanyABC123 and assigns it "AutoLISP" 
(vl-registry-write "HKEY_CURRENT_USER\\Software\\CompanyABC123" 

"String" "AutoLISP") 
"AutoLISP" 


; Reads the entry Integer under CompanyABC123 
(vl-registry-read "HKEY_CURRENT_USER\\Software\\CompanyABC123" "Integer") 
123 


The vl-registry-read function requires you to know the name of the value you want to 
read, but you might want to read all values under a key. You can use the vl-registry- 
descendents function to get the names of all the values under a key. After you have a list of the 
values under a key, you can then step through the list returned by vl-registry-descendents 
and get the data assigned to each value with vl-registry-read. 

Here is the syntax of the vl-registry-descendents function: 


(vl-registry-descendents key [mode]) 
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The key argument is the same as I previously described for the vl-registry-write and 
vl-registry-read functions. The mode argument is optional and can be a value of T. When 
T isn’t passed to the mode argument, a list of the subkeys is provided, whereas a value of T 
instructs vl-registry-descendents to return a list of values under the specified key. 

The following are examples of the vl-registry-descendents function and the values they 
return: 


; Returns the entries under CompanyABC123 

(vl-registry-descendents "HKEY_CURRENT_USER\\Software\\CompanyABC123" T) 
("String" "Integer") 

; Returns a list of the AutoCAD releases installed 
(vl-registry-descendents "HKEY_CURRENT_USER\\Software\\Autodesk\\AutoCAD" ) 
("R20.0" "R19.1") 


NOTE On Windows, you can use the vlLax-user-product-key and vlax-machine- 
product-key functions to return the key associated with the AutoCAD release executing the 
AutoLISP program. For example, vlax-machine-product-key returns “Software\\Autodesk\\ 
AutoCAD\\R20.0\\ACAD-E001:409” from the English version of AutoCAD 2015. For more in- 
formation on these two functions, see the AutoCAD Help system. 


Editing and Removing Entries 
You can update the data of a value under a key or remove a key or value that is no longer 
needed. Updating a value is done using the vl-registry-write function, whereas the 
vl-registry-delete function can be used to remove a key or value. vl-registry-delete 
returns T if the key or value is successfully removed; otherwise, nil is returned. 

The following shows the syntax of the vl-registry-delete function: 


(vl-registry-delete key [value_name]) 
Here are examples of the vl-registry-delete function: 


; Removes the Integer value from the CompanyABC123 key 
(vl-registry-delete "HKEY_CURRENT_USER\\Software\\CompanyABC123" "Integer") 
T 


; Removes the String value from the CompanyABC123 key 
(vl-registry-delete "HKEY_CURRENT_USER\\Software\\CompanyABC123" "Integer") 
nil 


; Removes the CompanyABC123 key and all values under it 
(vl-registry-delete "HKEY_CURRENT_USER\\Software\\CompanyABC123") 
T 
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USING CONFIGURATION FILES FOR STORING CUSTOM INFORMATION 


On Windows, before there was the Windows Registry, most applications used initialization (INI) 
files to store custom settings. Earlier AutoCAD releases used INI files and configuration (CFG) files 
to store device- and application-related settings. Recent AutoCAD releases still use CFG files for a 
few features, but mainly to support older custom programs that use CFG files for storing custom 
information. 


The getcfg and setcfg functions allow you to read from and write to the "AppData" section 
of the CFG file. The first argument of both functions is a string that represents an entry name 
under "AppData" in the CFG file, which is similar to the key and value name used with the 
vl-registry-write function. For example, the following sets the value of "AutoLISP" to 
the entity name "CompanyABC123/String" in the CFG file: 


(setcfg "AppData/CompanyABC123/String" "AutoLISP") 


The following gets the data from the "String" entity name: 
(getcfg "AppData/CompanyABC123/String") 


The setcfg and getcfg functions accept and return data of the string type only. 


Accessing Data from External Files 


AutoLISP supports the ability to read and write ASCII plain text, not binary files. You can read 
data stored in an ASCII file with AutoLISP and use that data to create general notes, add dis- 
claimers, or even populate the values of the attributes in a title block. In addition to reading files, 
AutoLISP can be used to write data to an ASCII file, which might represent an exported BOM 

or the properties of the layers in a drawing. ASCII files can be used to define any number of file 
types, such as CSV, text (TXT), HTM/HTML, or even XML. 


NOTE On Windows, you can use ActiveX/COM to access files that can be opened from a 
Microsoft Office application. I explain how to use ActiveX/COM with AutoLISP in Chapter 12, 
“Working with ActiveX/COM Libraries (Windows only).” 


Opening and Creating an External File 


AutoLISP can open an existing or create a new ASCII file that is currently stored on a local or 
network drive. Use the AutoLISP open function to open a file for read or write. The open func- 
tion returns a file pointer that is expressed as a FILE data type or nil if the file couldn't be 
opened. The file pointer returned by the open function is required to read from and write to 


232 


CHAPTER8 WORKING WITH THE OPERATING SYSTEM AND EXTERNAL FILES 


the file, as well as to save and close the file. I explain how to read text from a file in the next sec- 
tion, and how to write text in the “Writing Characters and Lines from a File” section later in this 
chapter. I discuss how to save and close a file in the “Closing an Open File” section. 


NOTE Trying to open a file that is read-only or that is stored in a read-only location with the 
write or append access mode results in the open function returning a value of nil, which 
indicates that the file couldn't be opened. Be sure to check the return value of the open function 
before trying to write to a file. 


The following shows the syntax of the open function: 
(open filename mode) 


Its arguments are as follows: 


filename The filename argument is a string that represents the file you want to open or 
create. 


mode The mode argument is a single character that represents the access mode you want to 
use to open or create the file. Valid values are "r", "w", and "a", as Table 8.1 shows later in 
this chapter. 


Here is an example of opening a file with the open function: 


; Opens a file named data.txt in C:\Dataset (Windows) 
(setq file_ptr (open "c:\\dataset\\data.txt" "r")) 
#<file "c:\\dataset\\data.txt"> 


; Opens a file named data.txt in /Dataset (Mac OS) 
(setq file_ptr (open "/dataset/data.txt" "r")) 
#<file "/dataset/data.txt"> 


NOTE File paths require the use of a single forward slash (Mac and Windows) or two backward 
slashes (Windows only) to separate drive and directory paths. 


While the filename argument can specify any ASCII file on a local or network drive, the 
name of the file and path you choose can affect the sustainability of your custom program. 
When you specify the filename argument for the open function, consider the following: 


Static Filenames When you read text from a file, using a static filename might be ideal, but 
static filenames don’t work well when you want to write data to a file. When creating a file, 
either allow the user to specify a filename with the getfiled function or use the 
vl-filename-mktemp function to get a unique temporary filename. 


Hard-Coded Paths I recommend against placing specific file paths in a custom program. 
Rather than hard-coding (typing the actual path to a particular file) a path or drive as part 
of a filename, use paths stored in system or environment variables related to the operating 
system or returned by the findfile function. For example, you can get the paths to 
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My Documents (or Documents) or the temporary files directory with the mydocumentsprefix 
and tempprefix system variables. 


I explain how to use the get filed and findfi le functions in the “Locating and Listing Files 
and Directories” section later in this chapter. 

The mode argument of the open function supports three different options. Table 8.1 lists and 
describes the file access modes that the open function supports. 


TABLE 8.1: ASCII file access modes 


ACCESS MODE DESCRIPTION 


read ("r") Read-only; changes to the file aren’t allowed. If the file doesn’t exist, nil is 
returned, indicating the file couldn't be opened. 


write ("w") Read and write; changes to the file are allowed. If a file with the same name exists, 
the file is overwritten. The file is created if it doesn’t already exist. 


append ("a") Read and write; changes to the file are allowed. Ifa file with the same name exists, the 
file is opened but not overwritten like with the write access mode. Any data written 
to the file is simply appended to the end. The file is created if it doesn’t already exist. 


The following shows the syntax of the v_- fi Lename-mktemp function: 
(vl-filename-mktemp [base_filename file_directory file_extension]) 


Its arguments are as follows: 


base_filename The base_filename argument is an optional string that represents the base 
filename of the temporary file you want to create. AutoLISP appends a numeric value to the 
end of the file, or between the filename and file extension if a file extension is provided. If a 
value is not passed to the base_filename argument, AutoLISP creates a file that starts with 
$VL~~ and doesn’t append a file extension unless a value for the file_extension argument is 
provided. 


file_directory The file_directory argument is an optional string that represents the 
directory in which the temporary file should be created. If no value is provided for the file_ 
directory argument, the directory is determined by the current AutoCAD user profile and 
operating system. 


file_extension The file_extension argument is an optional string that represents the 
extension that should be applied to the filename if one wasn’t provided as part of the base_ 
filename argument. 


NOTE Youcan specify a filename, path, and extension as part of the base_filename argu- 
ment and not provide any additional values for the file_directory and file_extension 
arguments. 
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Here are examples of creating temporary filenames with the vl- fi Lename-mktemp function: 


(vL-filename-mktemp) 
"C:\\Users\\Lee\\AppData\\Local\\Temp\\$VL~~001" ; Windows 
"/Users/lLeeambrosius/Documents/$VL~~001" ; Mac OS 


(vl-filename-mktemp "data.txt") 
"C:\\Users\\Lee\\AppData\\Local\\Temp\\data002.txt" ; Windows 
"/Users/leeambrosius/Documents/data002.txt" 3 Mac OS 


(vl-filename-mktemp "data" (getvar "mydocumentsprefix") ".txt") 
"C:\\Users\\Lee\\Documents\\data003.txt" ; Windows 
"/Users/leeambrosius/Documents/data003.txt" ; Mac OS 


If you write to a temporary file and want to keep the file with a more meaningful name or 
move it to a different directory, you can use the vl- fi le-copy and vl-file-rename functions. I 
mention these functions in the “Managing Files and Directories” section later in this chapter. 


Reading Characters and Lines from a File 


Once a file has been opened for reading, you can step through the data stored in the file one 
character or line at a time. The read-char function allows you to read the first character in a file 
and returns the ASCII value of the character as an integer. Each successive call to the function 
gets the next character in the file and returns the ASCII value of that character. nil is returned 
when there are no additional characters to be read from the file. 

Reading one character at a time isn’t always a practical way of reading data from a file. 
Instead, you can read an entire line of text. A line is defined as a text string that ends witha 
new linefeed character, which has an ASCII code value of 10. You use the read- line function 
to read a line of text from a file. Similar to the read-char function, each successive call to the 
read-line function gets the next line in the file, and the function returns nil when there are no 
additional lines of text in the file to read. 

The following shows the syntax of the read-char and read- line functions: 


(read-char [file_pointer]) 
(read-line [file_pointer]) 


The file_pointer argument is optional and must be of the FILE data type when provided. 
The value must be one that was returned by the open function. If the file_pointer argument 
isn’t provided, AutoCAD will allow you to enter one or more characters at the Command 
prompt. When the read-char function is used, the return value is the ASCII code value for the 
text entered; otherwise, a string containing the entered text is returned if the read- line func- 
tion was used. 

Here are examples of reading content from a file with the read-char and read-line 
functions: 


(read-char file_ptr) 
66 
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(read-line file_ptr) 
"BLOCK\tTAG\tPART\tDESCRIPTION" 


Listing 8.1 shows how to read all lines in a text file. 


LISTING 8.1: Custom function that reads all lines in a text file 


; Custom function opens the file for read and outputs each line 
(defun ReadFile (filename / fileptr cnt) 
(setq file_ptr (open filename "r")) 


(if file_ptr 
(progn 
setq cnt 1) 


while (setq text_line (read-line file_ptr)) 
(prompt (strcat "\nLine " (itoa cnt) ": " text_line)) 
(setq cnt (1+ cnt)) 


close file_ptr) 


) 
(princ) 


) 


; Function usage example 
(ReadFile "C:\\Dataset\data.txt") ; Windows 
(ReadFile "/Dataset/data.txt") ; Mac OS 


NOTE Ifyou read a character from a file with the read-char function and then call read- 
Line, the line of text returned will include only characters that have not yet been returned by 
the read-char function. Be careful when using both functions in the same file; I recommend 
using either read-char or read-line, and not both, in a custom program. 


Writing Characters and Lines from a File 


Writing data to a file is similar to reading data from a file. You can write a single character or 

a line of text to a file. The write-char function is used to write a single character to a file (the 
character is based on its ASCII code value), whereas the write- line function is used to write a 
line of text to a file. When you write individual characters to a file and want to end a line, you 
pass the write-char function an ASCII code value of 10—the linefeed character. A linefeed 
character is added to the end of the text that is written with the write- line function. 
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The following shows the syntax of the write-char and write-line functions: 


(write-char number [file_pointer]) 
(write-line string [file_pointer]) 


The arguments are as follows: 


number The number argument is an integer that represents the ASCII code value of the char- 
acter to be written to the file specified by the file_pointer argument. 


string The string argument is a string that represents the line of text to be written to the 
file specified by the file_pointer argument. 


file_pointer The file_pointer argument is optional and must be of the FILE data type 
when provided. The value must be one that was returned by the open function. If the file_ 
pointer argument isn’t provided, AutoCAD displays the character or text in the command- 
line window, similar to the prompt function. 


Here are examples of writing content to a file with the write-char and write-line 
functions: 


(write-char 66 file_ptr) 
C 


(write-line "4\tP366\tPNL3666" file_ptr) 
4 P366 PNL3666 


Closing an Open File 
Each file that you open or create with the open function must be closed using the close func- 
tion. Closing the file removes it from memory, thereby making it available to other applications, 
and commits any changes to the file that were made with the write-char and write-line 
functions. Files that aren't closed remain open in memory and unavailable to other applications 
until AutoCAD is closed. Closing AutoCAD closes the file, since AutoLISP is executed in the 
AutoCAD memory space. However, you shouldn’t rely on AutoCAD to close the file because it is 
possible that the file could remain locked in memory until Windows or Mac OS is restarted. 

The following is the syntax of the close function: 


(close file_pointer) 


The file_pointer argument that the close function expects is the same value that was 
returned by the open function. 
Here is an example of the close function: 


(close file_ptr) 
nil 
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Working with Directories and Files in the Operating 
System 


In addition to the ability to create, read, and write ASCII files, AutoLISP supports a wide range 
of file- and directory-management functions. Many of these file-management functions were 
added in AutoCAD 2000. The AutoLISP functions that are available for fileemanagement tasks 
allow you to do the following: 


@ Locate a file in the AutoCAD support file search paths or in a directory on a local or 
network drive 


Prompt the user for a filename or path 
Rename, copy, and delete files 


Create directories 


+ ¢ ¢ o 


Get information about a file: size, system time, filename, file path, and file extension 


Locating and Listing Files and Directories 

As I mentioned earlier, I don’t recommend hard-coding file paths in a custom program. 
AutoLISP provides several functions that can be used to locate a file or directory in the 
AutoCAD support file search paths or even outside AutoCAD in the operating system. 


LOCATING FILES IN THE AUTOCAD SUPPORT FILE SEARCH PATHS 


AutoCAD uses a set of locations defined with the options command, known as support file 
search paths. These locations are used by AutoCAD to find blocks to insert, AutoLISP files to 
load, customization files to control the user interface, and much more. You can use the AutoLISP 
findfile function to locate the first instance of a file within the AutoCAD support file search 
paths. The findfi le function returns either the full path of the file it is passed or nil if the file 
isn't located in one of the directories that are part of the AutoCAD support file search paths. 

The following shows the syntax of the findfi le function: 


(findfile filename) 


The filename argument is a string that represents the name of the file you want to locate 
within the AutoCAD support file search paths. 
Here is an example of the findfi le function and the value it returned: 


; Windows example 
(findfile "acad.pgp") 
"C:\\Users\\Lee\\appdata\\roaming\\autodesk\\autocad 2015\\ 
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R20.0\\enu\\support\\acad.pgp" 


; Mac OS example 

(findfile "acad.pgp") 
"/Users/leeambrosius/Library/Application Support/Autodesk/ 
roaming/AutoCAD 2015/R20.0/enu/support/acad.pgp" 


(findfile "ral classic.acb") 
nil 


WHERE’Ss My FILE? 


The findfi le function doesn’t search subdirectories, but you can add a relative path to a file that 
is contained in a subdirectory of one of the AutoCAD support file search paths. For example, on a 
Windows system the AutoCAD install directory is listed as a support file search path (C:\Program 
Files\Autodesk\AutoCAD 2015). The AutoCAD install folder contains a subdirectory named 
Sample, which isn’t part of the AutoCAD support file search paths. Under the Samp le subdirectory 
is the VBA subdirectory, and it contains a file named attext.dvb (C:\Program Files\Autodesk\ 
AutoCAD 2015\Sample\VBA\attext.dvb). So, if you enter the following, the findfi le func- 
tion returns ni l: 


(findfile "attext.dvb") 


ni lis returned because the attext.dvb file isn’t contained in one of the directories listed in the 
AutoCAD support file search paths; it’s hiding in a subdirectory. 


You could locate the file attext. dvb by using the following example: 


(findfile "sample\\vba\\attext.dvb") 
"C:\\Program Files\\Autodesk\\AutoCAD 2015\\sample\\vba\\attext.dvb" 


In addition to the findfi le function, you can use the findtrustedfi le function to locate 
a custom program that is in the AutoCAD support file search and trusted paths. The 
findtrustedfile function accepts a filename and returns the location of the file if it is trusted 
or nil if the file isn’t trusted. You'll learn about trusted paths in Chapter 10, “Authoring, 
Managing, and Loading AutoLISP Programs.” 


BROWSING FOR A FILE 


There might be times when you or the user of your custom program want to choose a particular 
ASCII file. Although you could use the getstring function and ask the user for a filename and 
path, the AutoLISP get filed function does provide you with a basic file-navigation dialog box. 
Figure 8.1 shows an example of a dialog box that is titled Create BOM File; this dialog box allows 
the user to specify the location of an ASCII file with the .bom file extension. The 

getfiled function returns either a string containing the filename and path specified or nil if 
the user clicks Cancel. 


File-navigation dia- 
log box displayed 
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a Create BOM File 
Save in: B MyCustomFiles MRE) 5 J e iv @ EA) 
with the getfiled Name i Date modified Ty 


No items match your search. 


< > 

File name: Drawing1.borm v Save 

Save as type: “bom v Cancel 
Reks) Create BOM File 

Save As: Drawing 1.bom ] Sy 
Tags: 
Where: | C Documents $j 
File Format: | *.bom $ 


The following shows the syntax of the getfi led function: 
(getfiled title filename file_extension mode) 


Its arguments are as follows: 


title Use the title argument to specify a string that represents the title for the dialog box. 


An empty string ("") indicates that the title should be set based on the value specified by the 
mode argument. If you don’t want to display a title, provide a string with a space ("_"). 


filename The filename argument is a string that represents the default filename and path 
that you want the dialog box to use. An empty string ("") opens the dialog box to the default 
directory, which is typically My Documents on Windows and Documents on Mac OS. 


file_extension The file_extension argument is a string that represents the default file 
extension for filtering the files list or creating new files. You can specify multiple file exten- 
sions by separating the entries with a semicolon, such as "bom; txt" to support BOM and 
TXT files. An empty string ("") or asterisk (*) sets the file type support for the dialog box to 
All Files (* .*), which displays all file types. 


mode The mode argument is an integer that represents a bitcoded value that can contain one 
or more bitcodes. Table 8.2 lists a few of the available bitcodes. 


You can learn about the other available modes by searching on the get filed function in the 
AutoCAD Help system. 
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TABLE 8.2: File-browsing mode argument bitcodes 
CODE DESCRIPTION 
1 Indicates that a new file is being created; the Save button is displayed instead of Open. 
4 Allows the user to enter a filename with or without a file extension. 
16 Allows you to specify only a file path as part of the fi Lename argument. 
32 Indicates that the user shouldn’t be prompted when overwriting a file with the same name; 


the existing file is replaced with the new file. 


128 URLs are not allowed. 


The following code shows the code statement that was used to display the dialog boxes in 


Figure 8.1: 
(getfiled "Create BOM File" "" "bom" 1) 
"C:\\Users\\Lee\\Documents\\MyCustomFiles\\Drawing1.bom" ; Windows 
"/Users/leeambrosius/Documents/MyCustomFiles/Drawingl.bom" ; Mac OS 


NOTE On Windows, if you have Express Tools installed you can use the acet-ui-pickdir 
function to display a Browse For Folder dialog box, which allows the user to select a directory 
only. This function is not documented and might be removed in the future, so use it at your 
own risk. 


LISTING THE FILES IN A DIRECTORY 


The findfile and findtrustedfi le functions are limited to searching for files in the 
AutoCAD support file search and trusted paths. You can use the vl-directory-files func- 
tion to get a list of the files or subdirectories in a specified path, you can then step through 
the list returned to get the subdirectories and files in a directory. The vl-file-directory-p 
function can be used to determine if a string contains a valid filename or directory. The 
vl-file-directory-p function returns T if the string it is passed is of a valid directory path; 
otherwise, nil is returned. 

The following shows the syntax of the v_-directory- files function: 


(vl-directory-files [directory filter mode]) 


The arguments are as follows: 


directory The directory argument is an optional string that represents the directory that 
you want to get subdirectories or files from in the form of a list. 


filter The filter argument is an optional string that represents the file pattern for filter- 
ing out the subdirectories and files that shouldn't be in the list returned by the function. 


mode The mode argument is an optional integer that controls the list returned by the func- 
tion: subdirectories only (-1), files and subdirectories (0), or files only (1). 
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The following shows the syntax of the v_- file-directory-p function: 
(vl-file-directory-p directory) 


The directory argument is a string that represents the directory path you want to verify. 
Here are some examples of the vl-directory-files and vl-file-directory-p functions: 


; Returns the DOCX files in the My Documents or Documents folder 
(vl-directory-files (getvar "mydocumentsprefix") "*.docx" 1) 
("Agreement 2014.docx") 


; Determines if the Temp directory exists on the main drive (Windows) 
(vl-file-directory-p "c:/temp") 
nil 


; Determines if the Temp directory exists on the main drive (Mac OS) 
(vl-file-directory-p "/temp") 
nil 
Listing 8.2 shows an example of how you recursively list all the subdirectories contained 
within a directory. Although this example scans for subdirectories only, you could use the 
vl-directory-files function to get a list of the files under each directory to locate a specific 
file that isn’t part of the AutoCAD support search paths. 


LISTING 8.2: Custom function that outputs subdirectory names under a specified directory 


; Recursive function used to step into each subdirectory 
(defun return-nested (parent_dir indent / dir) 
; Step through each value in the first returned 
(foreach dir (vl-directory-files parent_dir "*.*" -1) 
(if (and (/= dir ".")(/= dir "..")) 
(progn 
(terpri) 


; Output level indenting 

(setq indent (strcat indent "|-> ")) 

(prompt (strcat indent dir)) 

(setq indent (substr indent 1 (- (strlen indent) 4))) 


; Subdirectory found, recurse it as well 
(if (vl-file-directory-p (strcat parent_dir "\\" dir)) 
(return-nested (strcat parent_dir "\\" dir) (strcat indent "| ")) 


) 


) 
(princ) 


) 


; Main function that accepts the top directory to search 
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(defun RecurseDirectory (dir / indent) 
(setq indent "") 


; Check to see if the value passed is a valid directory 
(if (vl-file-directory-p dir) 
(progn 
(terpri) 
(prompt dir) 
; Begin recursing 
(return-nested dir indent) 


) 


(princ) 


; Function usage example 
RecurseDirectory "C:\\Program Files\\Autodesk\\AutoCAD 2015\\Sample") 


; Sample output 
C:\Program Files\Autodesk\AutoCAD 2015\Sample 
-> Activex 
-> ExtAttr 
-> ExternalCall 
-> Database Connectivity 
-> CAO 
-> en-us 
-> DesignCenter 
-> Dynamic Blocks 
-> Mechanical Sample 
-> Sheet Sets 
-> Architectural 
|-> Res 
-> Civil 
-> Manufacturing 
-> VBA 
-> VBAIDEMenu 


GETTING FILE LOCATIONS USING OS ENVIRONMENT VARIABLES 


Both Windows and Mac OS support environment variables. These are values that are specific to each 
operating system (OS), and some of them can be useful in gathering information about the OS and 
current user. Some OS environment variables contain paths that point to the location of the cur- 
rent user’s profile directory. From the user’s directory, you can get to the user’s AppData directory 
on Windows or the Library directory on Mac OS, which are used to store local and roaming files 
specific to the user. The getenv variable is used to obtain the value of an environment variable. 
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For example, you can use the userprofi le variable on a Windows OS to get the current user’s 
home directory; on a Mac OS, you can use the home environment variable to do the same. The 
following two examples show how to use the getenv function to get the value of an environment 
variable: 


(getenv "userprofile") ; Windows 
"C:\\Users\\Lee" 


(getenv "home") ; Mac OS 
"/Users/leeambrosius" 


The getenv function can also be used to get some of the AutoCAD application settings that are 
stored in the Windows Registry. You learned about the getenv function in Chapter 2. For more 
information about the environment variables that are supported by your OS, refer to the OS docu- 
mentation or use your favorite online search engine. 


Managing Files and Directories 

In addition to the functions that can be used to locate and list files, AutoLISP offers several 
functions that can be used to manage files that are stored on a local or network drive. These file- 
management functions are listed in Table 8.3. 


TABLE 8.3: AutoLISP file-management functions 
FUNCTION DESCRIPTION 
vl-file-rename Changes the name of an existing file. Can be used to copy a file whose name was 


< 


< 


< 


assigned using the vl- fi Lename-mktemp function. 


1-file-copy Creates a copy of an existing file with anew name. 
1-file-delete Removes an existing file; can’t be used to remove a directory. 
L-mkdir Creates a new directory. 


For more information on these functions, see the AutoCAD Help system. 


NOTE Although there are no AutoLISP functions that allow you to rename or remove a direc- 


tory, you could use AutoLISP to write a BAT or SH file, which could then be executed from 
the Windows Command prompt or Terminal on Mac OS with the startapp function. See the 


AutoCAD Help system for information on the startapp function. 
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Getting Information about a File 

Getting information about a file can be useful, even if it might be only to get the path in which 
a file resides or its file extension. Table 8.4 lists the functions that can be used either to get infor- 
mation about a file or to extract specific pieces of information from a file path. 


TABLE 8.4: AutoLISP file-related functions 
FUNCTION DESCRIPTION 
vl-file-size Returns the size of the file in bytes 
vl-file-systime Returns the last modification date and time for the file 
vl-filename-base Returns the name of the file without the path and file extension 
vl-filename-directory Returns the path to the file 
vl-filename-extension Returns the file’s extension 


For more information on these functions, see the AutoCAD Help system. 


NOTE On Windows, you can access a File System Object using ActiveX/COM, which can be 
used to access and manage files in the Windows operating system. I discuss how to use ActiveX 
with AutoLISP in Chapter 2. 


Exercise: Reading and Writing Data 


In this section, you will create two new functions that read data from and write data to external 

files. The first function reads information from a data file and uses that information to add new 

layers to a drawing. The second function is an extension of the BOM program that you created 

in Chapter 7. Instead of adding a table grid to a drawing, this new function exports the BOM 

content to a comma-delimited file that can be imported into a database or spreadsheet program. 
The key concepts I cover in this exercise are as follows: 


Storing Custom Information Information obtained during the execution of a custom pro- 
gram can be written to the Windows Registry or a Plist file on Mac OS. The information, once 
stored, can then be read back the next time the program is executed, and used as needed. 


Locating and Prompting for External Files Files that a custom program might rely on can 
be located in the AutoCAD support file search paths before they are used, or the user can be 
prompted for a filename and location. 


Opening, Reading, and Writing Data in External Files Data files can be opened before the 
data in the file can be read or data can be written to. Once file access is no longer needed, the 
file should be closed. 


EXERCISE: READING AND WRITING DATA 


NOTE Thestepsin this exercise depend on the completion of the steps in the “Exercise: Creating 
and Incrementing Room Labels” section of Chapter 7. If you didn’t complete the steps, do so 
now or start with the ch08_building_plan.dwg, ch08_layers.dat, ch08_furntools 
. lsp, and ch08_utility.lsp sample files available for download from www. sybex.com/go/ 
autocadcustomization. These sample files should be placed in the MyCustomF7 les folder 
under the Documents (or My Documents) folder, or the location you are using to store the LSP 
files. After the files are saved to the location you are using to store LSP files, remove ch08_ 
from the filenames. 


Creating Layers Based on Data Stored in an External File 


Often you start a drawing from a drawing template, which contains a default set of layers, but 
any layers not used can accidentally be removed with the purge or -purge command. To restore 
the missing layers, you could create a drawing that contains your default layers and insert it into 
your drawing. As an alternative on Windows, you could restore the layers using the Content 
Explorer or the AutoCAD DesignCenter™ palette. An additional approach to restoring layers or 
named standards is through the use of external data files and AutoLISP. 

The ch08_layers.dat file (part of the sample files supplied with this book) contains infor- 
mation that can be used to create layers in a drawing. The createlayer function is defined in 
the utility. lsp file. The DAT file is tab-delimited and contains three pieces of information 
about a layer. The information in each line is a layer name, color, and linetype: 


; AutoCAD Customization Platform 
; Layer data file used to setup layers 
Plan_Cabinets 6 Continuous 


Plan_Dimensions 3 Continuous 


In these steps, you'll create a custom function named loadlayers that reads and uses the 
data stored in the file named ch08_layers.dat to create new layers in a drawing: 


1. Create a new LSP file named loadlayers.1lsp with Notepad on Windows or TextEdit on 
Mac OS. 


2. In the text editor area of the loadlayers. Lsp file, type the following; the comments are 
here for your information and don’t need to be typed: 


; Creates layers based on the values in the chO08_layers.dat file. 
(defun c:LoadLayers ( / layerDataFile lastLoc file_ptr line 
tabLoc layerList lineTemp) 
; Select the layer data file, if not found 
; in the AutoCAD support file seach paths 
(if (= (setq layerDataFile (findfile "ch08_layers.dat")) nil) 
(progn 
; Get the location of the previously selected DAT file 
; from the Windows Registry/PLIST file 
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(setq lastLoc (vl-registry-read "HKEY_CURRENT_USER\\Software\\Sybex\\ 
ACP" 
"LastLayerDataFile") ) 


; Make sure the value in the Windows Registry/PLIST file is valid 
(if (= (type lastLoc) 'STR) 
(setq lastLoc (findfile lastLoc)) 


; If the file is not valid, prompt for the file 
(if (= lastLoc nil) 
(progn 
(setq lastLoc "") 
(setq layerDataFile (getfiled "Select Layer Data File" lastLoc "dat" 
8)) 
) 
(setq layerDataFile lLastLoc) 


; Store the last location to the Windows Registry/PLIST file 
(if layerDataFile 
(vl-registry-write "HKEY_CURRENT_USER\\Software\\Sybex\\ACP" 
"LastLayerDataFile" lLayerDataFile) 


; Check to see if the user selected a file 
(if layerDataFile 
(progn 
; Open the file for read-only 
(setq file_ptr (open layerDataFile "r")) 


; Step through the file 
(while (setq line (read-line file_ptr)) 


(if (/= (substr line 1 1) ";") 
(progn 
; Reset the variables 
(setq layerList nil lineTemp line) 


; Split the line into elements of a list based on tab characters 
(while (setq tabLoc (vl-string-search (chr 9) line)) 
(setq layerList (append layerList 
(list (setq lLineTemp 
(substr line 1 tabLoc))) 
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)) 
(setq line (substr line (+ tabLoc 2))) 
) 


; Add the last part of the line to the list 
(setq layerList (append layerList (list line))) 


; If the list is not empty, use the info to create a new layer 
(if layerList 
(createlayer (car layerList) (atoi (cadr layerList))) 
) 
) 
) 
) 


; Close the file 
(close file_ptr) 
) 
) 
(princ) 


) 
3. Click File > Save. 


Adding Layers to a Drawing with the loadlayers Function 


The loadlayers. lsp file contains the main loadlayers function, which uses the createlayer 
function defined in the utility. lsp file. 


NOTE The following steps require a data file named ch08_layers.dat. If you didn’t 
download the sample files previously, download them now from www. sybex.com/go/ 
autocadcustomization. Place these sample files in the MyCustomF7 Les folder under the 
Documents (or My Documents) folder. 


The following steps explain how to use the loadlayers function that is in the loadlayers 
. Lsp file: 


1. Create a new drawing. 


2. Start the appload command. Load the LSP files loadlayers. tsp and utility. lsp. If the 
File Loading - Security Concerns message box is displayed, click Load. 


3. At the Command prompt, type loadlayers and press Enter. 


4. Ifthe Select Layer Data File dialog box opens, browse to and select the ch08_layers.dat 
file, which you should have copied to the MyCustomFi les folder under the Documents 
(or My Documents) folder. The Select Layer Data File dialog box is displayed only if the 
AutoLISP program couldn't locate the ch08_layers.dat file. 


5. Click Open. 
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Do one of the following and review the layers that have been added: 
@ On the ribbon, click the Home tab > Layers panel > Layer Properties (Windows). 
@ On the Layers palette, click the Layers drop-down list (Mac OS). 


Open the ch08_layers.dat file in Notepad on Windows or TextEdit on Mac OS using the 
same process you follow to open an LSP file. 


Click at the end of the last line; it starts with Plan_Walls. 


9. In the text editor area, type the following (press the Tab key rather than typing the 


10. 
11. 


text <tab>): 
Title_Block<tab>7<tab>Continuous 
Save the changes to the ch08_layers.dat file. 


In AutoCAD, run the loadlayers function again; notice that the layer Title_Block is 
now added to the drawing. 


Writing the Bill of Materials to an External File 


In Chapter 7, you created a set of functions that allowed you to extract the attributes of a block 
and then quantify the results before creating the BOM in the drawing. Here, you will create a 
function named furnbomexport that allows you to export the BOM data generated with the 
extAttsFurnBOM function output to an external file instead of adding it to the drawing as a table 
grid as you did with the furnbom function. 

Using these steps, you will create the custom function named furnbomexport in the file 
furntools.lsp, which you created in Chapter 6. 


1. 
2. 


Open the furntools. lsp file with Notepad (Windows) or TextEdit (Mac OS). 


In the text editor area of the furntools. lsp file, click at the end of the last line in the file 
and press Enter twice. 


Type the following: 


; Exports the extracted attribute information to an external data file 
(defun c:FurnBOMExport ( / ssFurn eaList bomDataFile file_ptr item) 


; Get the blocks to extract 
(setq ssFurn (ssget '((0 . "INSERT")))) 


; If ssFurn is not nil proceed 
(if ssFurn 
(progn 
(setq bomDataFile (getfiled "Create CSV File" "" "csv" 1)) 


; Check to see if the user selected a file 
(if bomDataFile 


(progn 
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; Extract and quantify the parts in the drawing 
(setq eaList (extAttsFurnBOM ssFurn) ) 


; Open the file for read-only 
(setq file_ptr (open bomDataFile "w")) 


; Write the header line to the file 


7 


(write-line "QTY,LABELS,PARTS" file_ptr) 


3; Step through the list 
(foreach item eaList 
(write-line (strcat (car item) "," 
(cadr item) "," 
(caddr item)) file_ptr) 


; Close the file 
(close file_ptr) 
) 
) 
) 
) 


(princ) 


) 
4. Click File > Save. 


Using the furnbomexport Function 


The furntools.1sp file contains the main furnbomexport function, but some of the helper 
functions in furntools.lsp use functions defined in the utility. lsp file. 


NOTE The following steps require a drawing file named ch08_building_plan. dwg. If you 
didn’t download the sample files previously, download them now from www. sybex.com/go/ 
autocadcustomization. Place these sample files in the MyCustomF7 Les folder under the 
Documents (or My Documents) folder. 


The following steps explain how to use the furnbomexport function that is in the 
furntools. lsp file: 


1. Open ch08_building_plan. dwg. 


2. Start the appload command. Load the LSP files furntools.1lsp and utility. lsp. If the 
File Loading - Security Concerns message box is displayed, click Load. 


3. At the Command prompt, type furnbomexport and press Enter. 


4. Atthe Select objects: prompt, select the furniture blocks in the plan and press Enter. 
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5. When the Create CSV File dialog box opens, browse to the MyCustomF7 les folder or the 
folder in which you want to create the CSV file. 


6. In the File Name text box, type furnbom and click Save. 
7. Open Windows Explorer or File Explorer on Windows, or Finder on Mac OS. 


8. Browse to the location of the furnbom. csv file and open the file in Notepad, TextEdit, or 
even an application like Microsoft Excel. 


Figure 8.2 shows the results of opening the furnbom. csv file in Excel. 


FIGURE 8.2 A B C D 
BOM content in LABELS PARTS 
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Chapter 9 


Catching and Handling Errors 


As a veteran AutoLISP® programmer looking back over the past 15 years, I realize writing a 
custom program wasn't always the difficult part for me. The part of application development 
that didn’t come so naturally was predicting the unexpected. Programs are written based on a 
set of known criteria, which might include the current values assigned to system variables when 
the program was created, a specific set of steps that the user should follow, and what the end 
result should be. However, as in life, your program will have to handle a curve ball every now 
and then. 

As a programmer, you must learn to locate problems—errors or bugs, as programmers 
commonly refer to them. If you hang around programmers, you might have heard the term 
debugging, which is the industry-standard term used for the process of locating and resolving 
problems in a program. Conditional statements can be used to identify and work around poten- 
tial problems by validating values and data types used in a program. As a last resort, a custom 
error handler can be used to catch an error and exit a program cleanly. 


Identifying and Tracking Down Errors 


Writing a program takes time, but what can often take more time is identifying why a program 
is not working correctly—or at all. Figuring out a problem within a custom program can drive 
you crazy; after all, the problem is right there in the code you wrote. 


NOTE Sometimes finding a peer, or someone else in the industry, who can review your code 
can be helpful in finding the problem. If you don’t know a specific individual who is willing 
to review your code, try visiting sites such as www. theswamp.org, www. augi . com, and forums 
. autodesk. com for some help. 


Debugging is a skill that is honed over time, and it is something you start learning on your 
first day of writing AutoLISP—or any programming language, for that matter. These basic tech- 
niques can be useful in debugging an AutoLISP program: 


@ Executing a program one line at a time by pasting code at the Command prompt 
@ Displaying messages at the command line during execution 


@ Tracing a function and the values it is passed 
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TIP On Windows, the Visual LISP Integrated Development Environment (VLIDE) that comes 
with AutoCAD provides additional tools that can be helpful when debugging an AutoLISP pro- 
gram. I cover the VLIDE in Chapter 11, “Using the Visual LISP Editor (Windows Only).” 


Putting Your Code Under the Microscope 

Errors in an AutoLISP program aren't specific to any particular type of programmer; even the 
most veteran AutoLISP programmer can miss something in their code. The advantage a veteran 
programmer does have over those who are new to AutoLISP programming is an understanding 
of what to look for. When your program won't load, there are several things you should look at 
to try to fix the error. The following common errors are often responsible when your program 
does not load: 


Missing Closing Parenthesis It is common to miss one or more closing parentheses when 
you are working on a program. AutoLISP displays (_> or ; error: malformed list on input 
at the Command prompt to let you know you have more opening than closing parentheses. 
One opening parenthesis is displayed for each closing parenthesis that is needed when(_> is 
displayed. For example, (((_> indicates you need to add three closing parentheses to your pro- 
gram. The closing parentheses that are missing might or might not be together in the code. 
The resolution is to go through your code line by line, add the correct number of missing 
closing parentheses, and then try reloading the program. 


Missing Opening Parenthesis Much less common is a missing opening parenthesis, but it 
can happen. If you move lines of code around, a parenthesis could be overlooked. AutoLISP 
displays the error message ; error: extra right paren on input when there are more clos- 
ing parentheses than opening in your program. The resolution again is to go through your 
code line by line, add the missing opening parentheses or remove the extra closing parenthe- 
ses, and then try reloading the program. 


Missing Quotation Mark Strings that are missing a beginning or ending quotation mark 
will cause a problem when trying to load a program. AutoLISP will display (("_> at the 
Command prompt when this condition is encountered. If you are trying to display a quota- 
tion mark in a string, make sure you add the correct control sequence of \". The resolution is 
to find and add the missing quotation mark and then try reloading the program. 


Bad Argument Type One of the most obscure problems to track down in an AutoLISP pro- 
gram that won't load is related to a bad value. Typically, AutoLISP displays the error mes- 
sage ; error: bad argument type: conspor; error: extra cdrs in dotted pair on input 
when you have dotted pairs in your program that aren't structured correctly. The resolution 
is to locate the dotted pairs in your program and verify that they are structured correctly. 


TIP When adding a new function or line of code to an AutoLISP program, consider adding an 
opening and closing parenthesis right away before typing a function or argument value. If you 
are adding a string, add both the beginning and ending quotation marks to ensure you don’t 
forget one of them. Following these tips will help to keep your parentheses and quotation marks 
balanced and avoid some of the errors I previously described. 


Figure 9.1 shows a logic tree or analysis flowchart that you can refer to when troubleshooting 
and debugging problems in an AutoLISP file that won't load. 
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Once your program is loaded, you might still encounter problems. AutoLISP doesn’t validate 
whether a function exists or is being passed an appropriate value when it loads a program; it 
just checks for a valid structure and proper syntax. The following are common problems that 
you might encounter when executing a program: 


Bad Function AutoLISP displays the message ; error: bad function: <function_name> at 
the Command prompt when it encounters a function name it doesn’t understand. This could 
be the result of a misspelled name or a space missing between a function name and the first 
argument. The resolution is to search on the value after the colon in the AutoLISP program to 
locate the bad function name, and fix the name before reloading the program. If the function 
name is spelled correctly and the syntax is correct (no missing spaces), make sure that the 
program file that defines the function is loaded into AutoCAD. 


Bad Argument Type Unlike when you load an AutoLISP program and get the ; error: 

bad argument type message, this problem is often the result of trying to pass a function an 
unexpected value. The best technique to use is to display multiple messages throughout your 
custom program to isolate just where the error occurs. I explain how to add messages to a 
program for debugging purposes in the next section. 


Too Few/Too Many Arguments Functions expect a specific number of arguments; too 
few or too many results in an error. When AutoLISP displays the message ; error: too few 
arguments or ; error: too many arguments, check the number of arguments that is being 
passed to each function. Adding messages to a program can be helpful in identifying which 
statement is causing the error. I explain how to add messages to a program for debugging 
purposes in the next section. 


Figure 9.2 shows a logic tree or analysis flowchart that you can refer to when troubleshooting 
and debugging problems in an AutoLISP file that loads, but doesn’t execute. 
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Displaying Messages During Execution 

Using messaging functions to locate which statements in a custom program might be causing an 
error during execution may not make sense at first, but you can think of it like a game of Marco 
Polo between you and the program. Adding messaging functions is the equivalent of you call- 
ing out “Marco” and when a function is executed, the program calls back to you with “Polo.” 
You know when you are near the statement producing the error because the program doesn’t 
display the next debugging message. 

Place the message functions used for debugging about every 5 to 10 statements in a program; 
place them too frequently or infrequently, and they will not be as useful. The following is an 
example of a custom program that contains two errors that will cause some problems and shows 
how messaging functions can be used to help identify the bad statements: 


(defun c:BadCode ( / ) 
; Prompt for string 
(setq str (getstring "\nEnter a string: ")) 


; If str is not nil, continue 
(if str 
(progn 
(princ "DEBUG: Inside IF") 
(prompt "\nValue entered: " str) 
; Error 1, too many arguments 


; Prompt for integer 
(setq int (getint "\nEnter an integer: ")) 


(princ "DEBUG: Ready to divide") 
; Divide number by 2 
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(if int (prompt (strcat "\nDivisor" (itoa (/ 2 int))))) 
; Error 2 (possible) if user types 0 

) 

(princ "DEBUG: IF ELSE") 


) 
(princ "DEBUG: Inside IF") 


(princ) 


) 


The princ function in the previous example is used to display debugging-related messages 
during the execution of the program. The statement containing the prompt function causes an 
error because it doesn’t accept two arguments, and the / function causes an error if it tries to 
divide 2 by 0. 


TIP [recommend starting debugging messages with \nDEBUG: to make it easy to locate them ina 
program. By doing so, you can use the Find and Replace tools of Notepad (Windows) or TextEdit 
(Mac OS) to comment out debugging messages before you publish the finished program. Replace 
(princ "\nDEBUG: with ; (princ "\nDEBUG: to comment the statement out. 


The following functions can be used to display messages during the execution of a custom 
program: 


@ alert 
@ prinl 
@ princ 
@ = print 
@ prompt 


These message functions were covered in Chapter 5, “Requesting Input and Using 
Conditional and Looping Expressions.” 


NOTE The steps in the following exercise depend on the cho9_debuggingex.1lsp sample file 
available for download from www. sybex.com/go/autocadcustomization. The sample file should 
be placed in the MyCustomFiles folder within the Documents (or My Documents) folder, or the 
location you are using to store the LSP files. 


In this exercise, you will look at a custom program that has seen better days; it contains 
several errors that need to be identified and fixed. Some of the errors prevent the program from 
loading, whereas others cause the program to generate errors during execution. The following 
steps explain how to fix the errors in the file: 


1. Load Cho9_DebuggingEx.1sp into AutoCAD with the appload command. If the File Loading 
- Security Concern warning message is displayed, click Load to continue. 


AutoLISP displays the error message ; error: malformed string on input at the 
Command prompt. 
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2. Open the Ch09_DebuggingEx. lsp file in Notepad (Windows) or TextEdit (Mac OS). 


In the text editor area, you see the following code: 


(defun c:BadCode ( / str int) 
; Prompt for string 
(setq str (getstring "\nEnter a string: )) 


; If str is not nil, continue 
(if str 
(progn 
(prompt "\nValue entered: " str) 


; Prompt for integer 
(setq int (getint "\nEnter an integer: ")) 


; Divide 2 by a number 
(if int (prompt (strcat "\nDivisor: " (rtos (/ 2.0 int)))) 


(princ) 
) 
3. Scan the code for the missing quotation mark (“). 


Do you see it? It is missing at the end of the prompt string in the getstring 
function. 


4. Change "\nEnter a string: to"\nEnter a string: ". 
5. Save the file and reload it into AutoCAD. 
6. Scan the code line by line and count the number of opening and closing parentheses. 


Do you see it? A missing closing parenthesis can be much harder to locate than a missing 
quotation mark, but there is a technique you can use. 


7. Copy and paste one line at a time from the LSP file to the AutoCAD Command prompt 
and look to the left side of the command-line window. Evaluate the number of open 
parentheses each time you paste a new line until you see an extra open parenthesis. 


NOTE Instead of copying one line at a time, you can copy a whole AutoLISP function and paste 
it at the Command prompt as well; just don’t paste a command as the first line. 


The following shows the results of pasting each code statement to the Command prompt. 
The problem is not that there’s an extra opening parenthesis, but rather that a closing 
parenthesis is missing (as the last line here makes clear). The statement that is causing the 
error is (if int (prompt (strcat "\nDivisor: " (rtos (/ 2.0 int)))). 
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Command: (defun c:BadCode ( / str int) 
(> ; Prompt for string 


(_> (setq str (getstring "\nEnter a string: ")) 
(> 
(> ; If str is not nil, continue 
(> (if str 
((> (progn 
(( (> (prompt "\nValue entered: " str) 
(((> 
(((> ; Prompt for integer 
(((> (setq int (getint "\nEnter an integer: ")) 
(((_> 
(((> ; Divide 2 by a number 
(((_> (if int (prompt (strcat "\nDivisor: " (rtos (/ 2.0 int)))) 
((((_> ) 
E> J 
((_> 
((_> (princ) 
(>) 
8. In the text editor area, add the missing closing parenthesis to the end of the following 
statement: 
(if int (prompt (strcat "\nDivisor: " (rtos (/ 2.0 int)))) 


9. Save the file and reload it into AutoCAD. 
The file loads without any problems. 


In this exercise, you will test the custom program and fix any problems that might be 
encountered: 


1. At the Command prompt, type badcode and press Enter. 
2. Atthe Enter a string: prompt, type test and press Enter. 


AutoCAD displays the error message ; error: too many arguments at the 
Command prompt. 


3. In the text editor area, add the statements in bold to the file: 


(defun c:BadCode ( / ) 
; Prompt for string 
(setq str (getstring "\nEnter a string: ")) 


; If str is not nil, continue 
(if str 
(progn 
(princ "\nDEBUG: Inside IF") 
(prompt "\nValue entered: " str) 
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10. 


; Prompt for integer 
(setq int (getint "\nEnter an integer: ")) 


(princ "\nDEBUG: Ready to divide") 
; Divide 2 by a number 
(if int (prompt (strcat "\nDivisor: " (rtos (/ 2 int))))) 


) 
(princ "\nDEBUG: IF ELSE") 


) 
(princ "\nDEBUG: Inside IF") 


(princ) 


) 


Save the file and reload it into AutoCAD. 


The last message that AutoCAD displays before the error message is DEBUG: Inside IF. 
Look at the next statement after the message that contains the prompt function. Do you see 
the problem? The prompt function accepts only a single argument. 


Change the statement containing the prompt function to the following: 
(prompt (strcat "\nValue entered: " str)) 

Save the file and reload it into AutoCAD. 

At the Command prompt, type badcode and press Enter. 

At the Enter a string: prompt, type test and press Enter. 

At the Enter an integer: prompt, type 4 and press Enter. 


The custom function completes as expected and the following messages are displayed at 
the Command prompt. 


Command: BADCODE 

Enter a string: test 
DEBUG: Inside IF 

Value entered: test 
Enter an integer: 4 
DEBUG: Ready to divide 
Divisor: 0.5000 

DEBUG: Inside IF 


Run the badcode function again. When prompted for an integer value, type 0 and press 
Enter. 


The last message that is displayed is DEBUG: Ready to divide before the error message 
; error: divide by zero. To avoid the error related to dividing by 0, you should add a 
test condition to the program. 


The previous exercises demonstrate how the AutoLISP error messages are helpful in figuring 
out why a program doesn’t load or what is happening during execution. You also saw how 
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adding messages to a function can be helpful in figuring out where an error is occurring ina 
custom program. 


Tracing Functions 


AutoLISP provides a feature known as function tracing that allows you to be notified when 
a function is about to be executed and what it returns. You use the trace function to enable 
the tracing of a function and the untrace function to stop tracing a function. When tracing is 
enabled for a function, a message stating that the function is about to be executed is displayed 
at the Command prompt along with the arguments it was passed. Once the function is done 
executing, a message with the function’s return value is displayed at the Command prompt. You 
can trace both custom and standard AutoLISP functions. 

The following shows the syntax of the trace and untrace functions: 


(trace [function_name ...]) 
(untrace [function_name ...]) 


The function_name argument is the name of the function you want to enable tracing for (or 
that you no longer want to trace). The argument is optional, and when no function name is pro- 
vided, the function doesn’t do anything. If you want to trace more than one function, enter addi- 
tional function names and separate them with a space; don’t provide the function names in a list. 

Here is an example of tracing a custom function named OddOrEven: 


; Function returns ODD or EVEN based on the number it is passed 
(defun OddOrEven (cnt / ) 
(if (= (rem cnt 2) 1) 
"ODD" 
"EVEN" 


; Enable tracing of the OddorEven function 
(trace OddOrEven) 


; Function that loops 5 times and calls the OddOrEven function 
(defun c:TraceUntrace ( / ) 
(setq cnt 5) 


(while (> cnt 0) 
(OddOrEven cnt) 


(setq cnt (1- cnt)) 
) 


(princ) 


) 


; Output from the tracing of the OddOrEven function 
Entering (ODDOREVEN 5) 
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Result: "ODD" 
Entering (ODDOREVEN 4) 
Result: "EVEN" 
Entering (ODDOREVEN 3) 
Result: "ODD" 
Entering (ODDOREVEN 2) 
Result: "EVEN" 
Entering (ODDOREVEN 1) 
Result: "ODD" 


; Disable tracing of the OddorEven function 
(untrace OddOrEven) 


Catching Errors in a Program 


Even with all the effort put into identifying and locating errors in a custom program, an error 
can still occur during the execution. It is just in the nature of some functions to always return an 
error instead of nil when something unexpected happens. For example, dividing a number by 

0 always produces an error; the same goes for times when a custom function isn’t loaded when 
your program tries to call it. 

The vl-catch-all-apply function can be used to catch and then handle the error without it 
causing your program to suddenly end. The arguments passed to the vl-catch-all-apply func- 
tion are evaluated before the function returns a value. If no error occurs, either the expected 
value or a value of the Catch-All-Apply-Error data type is returned. 

The following shows the syntax of the vl-catch-all-apply function: 


(vl-catch-all-apply 'function_name 'argument_list) 
Here are its arguments: 


function_name The function_name argument is the name of the function you want to 
execute. The name must be prefixed with an apostrophe. 


argument_list The argument_list argument is a list that contains the arguments that 
should be passed to the function specified by the function_name argument. The argument 
list must be prefixed with an apostrophe. 


Here’s an example that shows how to catch an error with the vl-catch-all-apply function: 


; Divide 2 by 0 
(setq div (/ 2 @)) 
; error: divide by zero 


Idiv 
nil 


; Divide 2 by 1 
(setq div (vl-catch-all-apply '/ '(2 1))) 
2 
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; Divide 2 by 0 
(setq div (vl-catch-all-apply '/ '(2 0))) 
#<%catch-all-apply-error%> 


Idiv 
#<%catch-all-apply-error%> 


When you use the vl-catch-all-apply function, you can use the vl-catch-all-error-p func- 
tion to determine if an error was returned. 
The following shows the syntax of the vl-catch-all-error-p function: 


(vl-catch-all-error-p value) 


The value argument is a value of any supported data type. If the value is of the Catch-All- 
Apply-Error data type, T is returned and indicates that the return contains an error and not an 
expected data type, or nil if a value other than an error was returned. 

Here are examples of the vl-catch-all-error-p function: 


; Divide 2 by 1 
(vl-catch-all-error-p (setq div (vl-catch-all-apply '/ '(2 1)))) 
nil 


; Divide 2 by 0 
(vl-catch-all-error-p (setq div (vl-catch-all-apply '/ '(2 0)))) 
T 


The type of error returned by the vl-catch-all-apply function can be obtained with the 
vl-catch-all-error-message function. The vl-catch-all-error-message function returns a string 
value that represents the error, which you can use in a conditional statement to determine how 
the program should continue. Perhaps you will ask the user for a new value, substitute a default 
value, or not execute any further statements. 

The following shows the syntax of the vl-catch-all-error-message function: 


(vl-catch-all-error-message value) 


The value argument should contain a value of the Catch-All-Apply-Error data type. If an 
error is passed to the function, a string containing the error type is returned. Any value passed 
to the function results in the return of a new error. 

Here’s an example of the vl-catch-all-error-message function: 


; Divide 2 by 0 
(vl-catch-all-error-message (setq div (vl-catch-all-apply '/ '(2 0)))) 
"divide by zero" 


NOTE The apply function is similar to vl-catch-all-apply; you can pass a single function a 
list of values to use as the function’s arguments. However, the apply function will still result 
in the ending of the program if an error occurs. For more information on the apply function, 
see the AutoCAD Help system. 
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Defining and Using a Custom Error Handler 


Debugging and eradicating errors in a custom program (and catching those errors that might 
happen during execution) helps to ensure a great experience for the end user. However, even 
with all of this planning there are some situations you can’t handle using the techniques 
described so far in this chapter. As a last-ditch effort to handle any errors that might come up, 
AutoLISP provides the ability to implement a custom error handler that will give you a chance 
to clean up any changes to the AutoCAD environment. 


©) Real World Scenario 
No! Not THE Esc KEY! 


Here’s a situation that will always end with an error. You can’t catch it while you're programming 
because nobody is supposed to do that. When an end user presses Esc while being prompted for a 
value, AutoLISP cancels the current function and starts the current error handler. The standard 
AutoLISP error handler simply returns a message about the most recent error, but you can over- 
ride the standard AutoLISP error handler with your own error handler. I’ll show you how to use a 
custom error handler to catch the error and then respond accordingly. 


A custom error handler is a function defined with the defun function and should accept a 
single argument. The argument passed to the error handler is of the string data type, and it rep- 
resents the error that occurred. 

The standard error handler is represented by the function named *error*. You don’t directly 
call this function, but you do override it with your own custom error handler once it is defined. 
The *error* function is overwritten using the setq function, but before you do override it, I 
recommend that you store the current *error* function so it can be restored after your custom 
program ends. If you don’t restore the previous *error* function, it might cause problems with 
other custom AutoLISP programs. 

The following is an example of a basic custom error handler that doesn’t return an error 
message when the user presses Esc while being prompted for input with one of the getxxx 
functions: 


(defun *my_error*® ( msg / ) 
(if (/= (strcase msg T) "function cancelled") 
(alert (strcat "\nERROR: " msg)) 


(setq *error* old_err) 


) 


The following stores the current *error* function in the old_err variable, and then sets the 
*my_error* function as the current error handler that AutoLISP calls when an error occurs: 


(setq old_err *error* 
*error*® *my_error*) 
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This statement restores the previous error handler that was assigned to the old_err variable: 
(setq *error* old_err) 


The following function prompts the user for an integer and then divides 2 by that number. 
This is designed to deal with errors that occur if the user presses Esc instead of entering a num- 
ber or if 0 is entered. 


(defun c:TestEsc ( / int) 
(setq int (getint "\nEnter a whole number: ")) 
(alert (strcat "Value: " (itoa (/ 2 int)))) 

) 


As an alternative to the previous example, you could use a custom error handler to catch 
the error that might be generated by the function and then respond accordingly. The following 
function implements a custom error handler and displays an error message only when the user 
doesn’t press Esc: 


(defun c:TestEscErr ( / int) 
; Define the custom error handler 
(defun *my_error* ( msg / ) 
(if (/= (strcease msg T) "function cancelled") 
(alert (strcat "\nERROR: " msg)) 


(setq *error* old_err) 


) 


; Store the current error handler and set the custom error handler 
(setq old_err *error* 
*error* *my_error*) 


(setq int (getint "\nEnter a whole number: ")) 
(alert (strcat "Value: " (itoa (/ 2 int)))) 

; Restore the previous error handler 

(setq *error* old_err) 
(princ) 


) 


NOTE Acustom error handler has access to the local variables of the function in which the 
error occurred. 


Grouping Functions into a Single Undo Action 


Standard AutoCAD commands support the ability to be undone with a single action using 

the u or undo command. Using the undo command, you can wrap all the functions in a custom 
AutoLISP program to act like a single operation. This makes it easier to roll back changes that 
are made by a custom program and restore the drawing to the state it was in before the program 
was executed when an error is encountered or for the end user’s convenience. 
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If you don’t use the undo command to wrap the functions in a custom AutoLISP program, the 
undo command might need to be executed several (maybe even hundreds of) times to roll back 
the changes that were made. Objects created or modified with the command function would 
need to be rolled back one command at a time. However, objects created or modified without 
the use of the command function don’t support individual undoing, but rather are undone only 
after the changes made by the last individual command are undone. 

Figure 9.3 illustrates how commands are undone by default—one at a time—and also shows 
how objects created with the entmake function are undone when undo grouping is not used. The 
top of the illustration shows the circle command used twice and the line command used once; 
executing the u command three times would get you back to the drawing’s previous state. The 
bottom of the illustration shows the creation of a circle with the circle command, and then a 
line and circle created with the entmake function. Notice that the objects created with entmake are 
grouped with the previous command; in this case it was the circle command. Executing the u 
command will undo the line and circle created with the entmake function, along with the circle 
command. 


FIGURE 9.3 Default undo for objects created with individual commands 
Rolling back changes Undot Undo2 Undo3 

made with commands { Xf yf \ 

and the entmake circle line circle 

function command command command 


Default undo for objects created with entmake 


Undo1 
[ \ 
circle entmake entmake 
command line circle 


The BEgin suboption of the undo command is used to start a new undo grouping, whereas the 
End suboption marks the end of the undo grouping. Once a grouping is defined, the u or undo 
command will then roll back all the changes that were made as part of that grouping. Figure 9.4 
illustrates the same object-creation operations shown in Figure 9.3, but here the operations are 
wrapped in undo groupings. Undoing the changes now requires the end user to execute the u 
command only once to roll back all the changes included in the undo grouping. 

The following example demonstrates how to begin and end an undo grouping: 


; Create concentric circles 
(defun c:CCircs ( / cenPt rad) 
3; Start the undo grouping 


(command "._undo" "_be") 


; Prompt for center point 
(setq cenPt (getpoint "\nSpecify center point: ")) 
(entmake (list (cons © "CIRCLE") (cons 10 cenPt) (cons 40 0.75))) 
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; Prompt for radius 
(setq rad (getdist cenPt "\nSpecify radius of second circle: ")) 
(entmake (list (cons © "CIRCLE") (cons 10 cenPt) (cons 40 rad))) 


; End the undo grouping 
(command "._undo" "_e") 
(princ) 


) 
Here’s an example of using undo grouping with a custom error handler: 


; Create concentric circles 
(defun c:CCircs ( / cenPt rad) 


; Custom error handler 

(defun *my_error* ( msg / ) 
; Ends the previous undo grouping 
(command "._undo" "_e") 


; Roll back the changes 
(command "._u") 
(setq *error* old_err) 


3; Store the current error handler and set the custom error handler 


(setq old_err *error* 
*error*® *my_error*) 


3; Start the undo grouping 
(command "._undo" "_be") 


; Prompt for center point 
(setq cenPt (getpoint "\nSpecify center point: ")) 


(entmake (list (cons © "CIRCLE") (cons 10 cenPt) (cons 40 0.75))) 


; Prompt for radius 
(setq rad (getdist cenPt "\nSpecify radius of second circle: ")) 
(entmake (list (cons © "CIRCLE") (cons 10 cenPt) (cons 40 rad))) 


; End the undo grouping 
(command "._undo" "_e") 


; Restore the previous error handler 
(setq *error* old_err) 
(princ) 


) 
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FIGURE 9.4 Undo grouping objects created with commands 

Wrapping functions Undo 

with undo groupings \ 
tocreate:a single undo Undo circle line circle Undo 
action BEgin command command command End 


Undo grouping objects created with entmake 


Undo1 Undo2 
if \/ \ 


circle Undo entmake entmake Undo 
command BEgin line circle End 


Undo grouping objects created with a command and entmake 


Undo1 

{ \ 
Undo circle entmake entmake Undo 
BEgin command line circle End 


With the previous example, if the user presses Esc while being prompted for the radius, the 
program ends and undoes the drawing of the first circle. 

Starting with AutoCAD 2012, the way commands are called within a custom error handler 
was changed. If you are using the command-s function within a custom error handler, you must 
call the *push-error-using-stack* function before the *error* handler might be called. Then, 
after the last use of the command-s function, you must call the *pop-error-mode* function. 

The *push-error-using-command* function is similar to *push-error-using-stack*, but should 
be called when the command function is used in a custom error handler. When neither is called, 
AutoLISP assumes it is using *push-error-using-command* and it is okay to use the command 
function; this is the legacy behavior of AutoCAD 2011 and earlier releases. 

The *push-error-using-command*, *push-error-using-stack*, and *pop-error-mode* functions 
don’t accept any arguments. I show how to use the *push-error-using-command* and *pop-error-mode* 
functions in the next section. For an example of the *push-error-using-stack* function, see the 
AutoCAD Help system. 


TIP Examples of custom error handlers using the command and command-s functions can be 
found in the ch09_errhandlers.1lsp sample file available for download from ww.sybex.com/ 
go/autocadcustomization. 


Exercise: Handling Errors in the drawplate Function 


In this section, you will continue to work with the drawplate function that was originally 
introduced in Chapter 2, “Understanding AutoLISP.” The key concepts I cover in this 
exercise are as follows: 


EXERCISE: HANDLING ERRORS IN THE DREAPLATE FUNCTION 


Using Undo Grouping Wrapping functions into an undo grouping allows any changes that 
are made by a custom program to be rolled back and restores the drawing to the state it was 
in before it was executed. 


Adding a Custom *error* Handler Custom *error* handlers make it easy to determine 
when a program encounters an error and then to respond accordingly. 


NOTE The steps in this exercise depend on the completion of the steps in the “Exercise: 
Creating, Querying, and Modifying Objects” section of Chapter 6, “Creating and Modifying 
Graphical Objects.” If you didn’t complete the steps, do so now or start with the ch09_drawplate 
.lsp and ch09_utility.1lsp sample files available for download from www.sybex.com/go/ 
autocadcustomization. These sample files should be placed in the MyCustomF les folder within 
the Documents (or My Documents) folder, or the location you are using to store the LSP files. 
Once the sample files are stored on your system, remove the characters ch09_ from the name 


of each file. 


Using the drawplate Function 

Chapter 6 was the last chapter in which any changes were made to the drawplate function. At 
that time, the function drew a plate and added holes based on user input, which defined the 
overall size of the plate. But what if you made a mistake? Did you try to undo the changes that 
were made by the drawplate function or press Esc to cancel the function when being prompted 
for input? If you did, you found that the plate that was drawn remained in the drawing or the 
changes that were made to the drawing didn’t exactly roll back as expected. Typically when you 
cancel a command before it completes, all of the changes are undone, but not so with the draw- 
plate function. Use the following steps to see for yourself: 


1. Create a new drawing. 


2. Start the appload command. Load the LSP files drawplate.1sp and utility. sp. If the File 
Loading - Security Concerns message box is displayed, click Load. 


3. At the Command prompt, type drawplate and press Enter. 


4. Atthe Specify base point for the plate or [Width/Height]: prompt, pick a point in 
the drawing area to draw the plate and holes based on the width and height values 
specified. 


5. At the Specify label insertion point: prompt, press Esc. 


The plate that was drawn remains in the drawing. Typically, when you cancel a command 
before it completes all of its changes are undone. 


6. Run the drawplate function again. Specify a point for the plate and the label. 
7. At the Command prompt, type u and press Enter. 


Both the incomplete and complete plates are undone, not just the most recently drawn 
objects. 
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Implementing a Custom *error* Handler and Undo Grouping 
As you revise the functions, notice how easy it can be to change the underlying functionality 
of your programs when they are divided into several smaller functions. Smaller functions are 
easier not only to change, but to retest if a problem is encountered. 

The following steps explain how to update the drawplate function to include a custom 
*error* handler and undo grouping: 


1. Open the drawplate. lsp file in Notepad (Windows) or TextEdit (Mac OS). 


2. In the text editor area, add the text in bold: 
3; Custom error handler with command functions 
(defun err_drawplate (msg) 
(if (/= msg "Function cancelled") 
(alert (strcat "\nError: " msg) ) 


(command "._undo" "_e") 
(command "._u") 
3; Restore previous error handler 
(setq *error* old_err) 
(princ) 
) 
; Draws a rectangular plate that is 5x2.75 
(defun c:drawplate ( / ptl pt2 pt3 pt4 width height insPt textValue 
cenPtl cenPt2 cenPt3 cenPt4 old_vars hole_list) 


(setq old_err *error* *error* err_drawplate) 


3 Command function being used in custom error handler 
(*push-error-using-command* ) 


(command "._undo" "_be") 
; Store and change the value of the system variables 
(setq old_vars (get-sysvars '("osmode" "clayer" "cmdecho") )) 
(set-sysvars '("osmode" "clayer" "cmdecho") '(@ "o" 0)) 
3; <Code break...> 
; Save previous values to global variables 
(setq *drawplate_width* width) 
(setq *drawplate_height* height) 


(command "._undo" "_e") 


3; Restore previous error handler 
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(setq *error* old_err) 


3; End using *push-error-using-command* 
(*pop-error-mode* ) 


; Exit "quietly" 
(princ) 
) 


3. Click File > Save. 


Testing the Changes to the drawplate Function 
The following steps explain how to test the changes that were made to the drawplate function: 


1. Create a new drawing. 


2. Start the appload command. Load the LSP files drawplate.1sp and utility. sp. If the File 
Loading - Security Concerns message box is displayed, click Load. 


3. At the Command prompt, type drawplate and press Enter. 


4. Atthe Specify base point for the plate or [Width/Height]: prompt, pick a point in the 
drawing area to draw the plate and holes based on the width and height values specified. 


5. At the Specify label insertion point: prompt, press Esc. 


The plate that was drawn is removed from the drawing, thereby restoring the drawing to 
its previous state. 


6. Run the drawplate function again. Specify a point for the plate and label. 
7. At the Command prompt, type u and press Enter. 


The completed plate is undone as expected. 


Authoring, Managing, and Loading 
AutoLISP Programs 


Entering AutoLISP® expressions directly at the Autodesk® AutoCAD® Command prompt is a 
great way to start learning AutoLISP programming. However, if you want to use expressions mul- 
tiple times or in different drawings, you will need to enter them over and over again. 

Instead of entering AutoLISP expressions at the Command prompt, you can store them in an 
ASCII text file with a . lsp extension. In addition to entering AutoLISP expressions in a LSP file, 
you can add nonexecutable expressions known as comments, which allow you to make notes to 
yourself in the code. After you create a LSP file, you must load it into AutoCAD before any of the 
expressions stored in the file can be executed. 

Before loading a LSP file, you need to let AutoCAD know where it is located and that the 
location it is stored in is safe to load executable (LSP/ARX/DVB) files from. Once AutoCAD 
knows where your LSP files are located, you can then load them manually as needed, automati- 
cally at startup, or on demand. 


Storing AutoLISP Expressions 


Although you can enter AutoLISP expressions at the AutoCAD Command prompt, as part of 
a script file, or as a command macro used in the user interface, the most common method is 
to type them into a text editor and store them ina LSP file. AutoLISP programs are commonly 
stored in LSP files, but they can also be stored in menu AutoLISP (MNL) files. Menu AutoLISP 
files have the .mn1 file extension. 

MNL files contain AutoLISP programs that are used by command macros defined in a CUI/ 
CUIx file. When a CUI/CUIx file is loaded into AutoCAD, AutoCAD looks for and loads an 
MNL file with the same name as the CUI/CUIx file being loaded. For example, if the acad.cuix 
file is loaded, AutoCAD looks for and loads the acad.mn1 file if a file named acad.mn1? is found 
within the support file search paths defined in the Options dialog box (Windows) or Application 
Preferences dialog box (Mac OS). 


NOTE ALSP or MNL file must be saved to an ASCII text file, and it cannot include any special 
characters like a Rich Text or Microsoft Word document can. 


272 |CHAPTER10 AUTHORING, MANAGING, AND LOADING AUTOLISP PROGRAMS 


Once a LSP file has been created, the code stored in the file can then be loaded into the 
AutoCAD program when it is needed. I discuss the text editors that can be used to create a LSP 
file in the next section, and you'll learn how to load a LSP file later, in the “Loading AutoLISP 
Files” section. 


Selecting an Editing Environment 

You don’t have to buy additional software to create and edit AutoLISP program files, regardless 
of whether you are using Windows or Mac OS. Any of the following applications can be used to 
create or edit AutoLISP expressions stored in a LSP or MNL file: 


Notepad (Windows Only) Notepad allows you to create and edit plain ASCII text files and 
is installed with Windows. Although Notepad isn’t designed specifically for AutoLISP pro- 
gramming, it is the choice of many veteran AutoLISP developers. Notepad is the application 
you will primarily use with this book if you are using AutoCAD on Windows. 


Visual LISP® Editor (Windows Only) The Visual LISP Editor is a specialized development 
environment that is designed for working with AutoLISP programs stored in LSP or MNL 
files. This editor supports colored syntax and tools that help you identify missing parenthe- 
ses. Additionally, this editor allows you to load, format, check, and debug AutoLISP 
programs. I cover the Visual LISP Editor and its features in Chapter 11, “Using the Visual 
LISP Editor (Windows only).” 


TextEdit (Mac OS Only) TextEdit allows you to create and edit plain ASCII text files and 
is installed with Mac OS. Like Notepad on Windows, TextEdit isn’t designed specifically 
for AutoLISP programming, but it does contain all the basic editing features you want in 
an editor. TextEdit is the application you will primarily use with this book if you are using 
AutoCAD on Mac OS. 


Throughout most of this book, I focus primarily on the core concepts of the AutoLISP pro- 
gramming language; for that, I decided to keep things simple by using Notepad and TextEdit. 
However, once you are comfortable with AutoLISP and if you are on Windows, I strongly rec- 
ommend that you eventually make the transition to the Visual LISP Editor. If you are on Mac 
OS, the Visual LISP Editor isn’t available unless you install Windows and AutoCAD on Boot 
Camp or Parallels. If you do lots of AutoLISP development, the Visual LISP Editor can save you 
time writing and debugging. 


Creating an AutoLISP File 


As I previously mentioned, a LSP file is a plain ASCII text file. You can use Notepad on 
Windows or TextEdit on Mac OS to create a LSP file, but since both of these applications com- 
monly are used to work with TXT files, you will need to be sure to add the . lsp file extension to 
the files you create with these applications. If you are on Windows and want to use the Visual 
LISP Editor, consult the instructions in Chapter 11 for creating a LSP file. 


NOTE The examples in this section assume that you created a folder named MyCustomFiles 
in your Documents (or My Documents) folder on your local drive. If you have not created this 
folder, do so now, or if you created the folder in a different location, be sure you adjust the steps 
accordingly. 


STORING AUTOLISP EXPRESSIONS 


The following exercise explains how to create an AutoLISP file named mylisp.1sp on 
Windows: 


1. 


Do one of the following: 


@ On Windows XP or Windows 7, click the Start button > [All] Programs > Accessories 
> Notepad. 


@ On Windows 8, on the Start Screen, type notepad and then click Notepad when it 
appears in the search results. 


2. In Notepad, click File > Save As. 


n 


ye oy a 


8. 


In the Save As dialog box, browse to the MyCustomF7 les folder that you created under 
the Documents (or My Documents) folder, or to the location where you want to store the 
LSP file. 


In the File Name text box, type mylisp. lsp. 
Click the Save As Type drop-down list and select All Files (**). 
Click the Encoding drop-down list and select ANSI. Click Save. 


In the text editor area, type the following expressions. 
(defun c:MSG () (alert "First AutoLISP file.")) 
(prompt "\nVersion 1.0 - My AutoLISP Programs") 


The AutoLISP alert function displays a message box; the prompt function displays a 
message at the AutoCAD Command prompt. 


Click File > Save. 


NOTE [discussed the AutoLISP alert and prompt functions in Chapter 5, “Requesting Input 
and Using Conditional and Looping Expressions.” 


If you are running AutoCAD on Mac OS, use the following steps to create a LSP file named 
mylisp. lsp: 


1. 


In the Mac OS Finder, click Go > Applications. In the Finder window, double-click 
TextEdit. 


In TextEdit, click TextEdit > Preferences. In the Preferences dialog box, on the New 
Document tab click Plain Text and deselect Smart Quotes. Close the dialog box. 


If a document was open when you first started TextEdit, close it now. Changes to the 
settings affect only future documents, those you create or open after the changes were 
made. 


3. Click File > New to create a plain ASCII text file. 


4. Click File > Save and type mylisp. lsp in the Save As text box. From the sidebar on the 


left, click Documents > MyCustomFiles, or browse to the location where you want to 
store the LSP file. Click Save. 


If prompted to use the . lsp extension, click Use .Lsp. 
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6. In the text editor area, type the following expressions: 


(defun c:MSG () (alert "First AutoLISP file.")) 
(prompt "\nVersion 1.0 - My AutoLISP Programs") 


The AutoLISP alert function displays a message box; the prompt function displays a 
message at the AutoCAD Command prompt. 


7. Click File > Save. 


After saving the file, you can load it into AutoCAD using one of the techniques explained 
in the section “Using the Load/Unload Applications Dialog Box to Load a LSP File” later in 
this chapter. Figure 10.1 shows the results of loading the mylisp. lsp file in AutoCAD and then 
executing the MSG function at the Command prompt. 


FIGURE 10.1 
Loading a custom 
program 


First AutoLISP file. 


version 1.0 - My AutoLISP Programsnil 
Command: MSG 


Bi & AutoCAD Message 
First AutoLISP File. 


© Version 1.0 - My AutoLISP P 
Command: 
Command: MSG 


Command: ¥ L 


Editing an AutoLISP File 


You can edit LSP files using any of the applications described in the section “Selecting an 
Editing Environment” or any other application that supports editing plain ASCII text files. If the 
. Lsp file extension has been associated with an ASCII text editor, you can simply double-click 
the file to open it in the associated editor. When no editor is associated with the LSP file type 
and you double-click on a file of that type, you are prompted to select an editor to open the file. 
Associate an editor with the LSP file type and make the changes to the file. Save the file as a 
plain ASCII text file and reload it in AutoCAD to test the code changes in the file. 


WRITING MODULAR CODE 


Writing Modular Code 


When you first start writing AutoLISP programs, you may tend to create large self-contained 
functions. As you write, you will notice similarities in the functions that you create, whether it is 
creating or modifying graphical and nongraphical objects, or working with system variables. 

Instead of writing large functions that contain every expression required to solve a problem 
or complete a task, I recommend breaking large functions into smaller, more manageable, task- 
oriented functions. By breaking your functions down, you gain the following benefits: 


@ Code can be reused across many different functions, thereby reducing the size of your pro- 
grams when they are loaded into memory. 


@ Code can be revised to take advantage of newer techniques or desired code changes with- 
out having to make the same changes in one or many locations ina single file or across 
multiple files. 


¢@ Potential errors in a function are easier to identify and fix because there are fewer expres- 
sions to debug and evaluate. 


@ Smaller functions make great building blocks to introduce new functionality. 


The following is an AutoLISP function containing expressions that create and set as current 
a new layer named Object (or set the layer as current if it already exists) and draws a rectangle 
that is 6 x 3 units using the AutoCAD line command: 


(defun c:drawrectangle ( / ) 
(command ",_-layer" "om" "Object" UE cii 2 wee mi) 


(command "._line" '(0 0 0) 
'(6 © 0) 
'(6 3 0) 
"0 3:0)" eT) 
) 


Layers are common nongraphical objects in a drawing that are used to organize and control 
the display of graphical objects, such as lines and circles. Since layers are so common, you might 
consider creating a set of functions that are used to create a new layer or set a layer as current 
instead of repeating the same expressions in each of your functions. 

The following shows how you might break down the expressions in the drawrectangle 
function into two functions named createlayer and createrectangle. You can then reuse 
them in other custom functions. 


(defun createlayer (name color / ) 


(command "._-layer" "_m" name "_c" color "" "") 
) 
(defun createrectangle (ptl pt2 pt3 pt4 / ) 
(command "._line" ptl 
pt2 
pt3 
pt4 Wael) 
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The revised drawrectangle function would look like this: 


(defun c:drawRectangle ( / ) 
(createLayer "Object" 2) 


(createRectangle '(0 © 0) 
'(6 © 0) 
'(6 3 0) 
'(0 3 0)) 
) 


As I mentioned, creating smaller functions lets you reuse them fairly easily. The following 
shows a function named drawcircle that uses the function named createlayer to create and 
set a layer as current before drawing a circle: 


(defun c:drawcircle ( / ) 
(createLayer "Object" 2) 


(command "._circle" '(3 1.5 0) 1) 
) 


The drawrectangle and drawcircle functions in the previous examples use the 
createlayer function. Since these functions reference the same createlayer function, any 
changes to the create layer function affect both of the functions. For example, it isn’t ideal to cre- 
ate a new layer or modify that layer if it already exists in a drawing when you might simply want 
to just set the layer as current. The following is a revised version of the createlayer function 
that first tests to see whether the layer exists using the AutoLISP functions tblsearch and if: 


(defun createlayer (name color / ) 
(if (/= (tblsearch "Layer" name) nil) 
(setvar "clayer" name) 
(command "._-layer" "_m" name "_c" color "" "") 


) 


If the layer already exists, it is set as current by assigning the name of the layer to the clayer 
system variable. If the layer doesn’t exist in the drawing, it is then created and set as current. As 
you can see, proper planning of your code and using smaller functions makes it fairly easy to 
update your functions. I discuss the tblsearch function in Chapter 7, “Creating and Modifying 
Nongraphical Objects,” and the if function in Chapter 5. 


Adding Comments 


As a veteran programmer of over 16 years, I can honestly say that I formed my fair share of bad 
habits early on when first learning to program. One of the habits that I had to correct was 
adding very few comments (or not adding any) to my code. Comments are nonexecutable 
expressions that are stored as part of a LSP file. The concept of comments is not specific to 
AutoLISP alone but is part of most modern programming languages. The syntax used to indi- 
cate a comment varies from language to language. 


ADDING COMMENTS 


The following are common reasons why you might want to add comments to 


a LSP file: 

+  Todocument when the file was created and who created it. 

@ To maintain a history of changes made to the program—what changes were made, when, 
and by whom. 

To indicate copyright or legal statements related to the code contained in the file. 
To explain how to use a custom function—if any arguments are expected and the type of 
data they might expect. 

@ To explain what a set of AutoLISP expressions might be doing—you might remember what 
expressions are used for today, but it can become more of a challenge to remember what 
they are doing months or years later. 

@ To mask an AutoLISP expression that you currently don’t want to execute—during test- 


ing or while making changes to a program, you might want to temporarily not execute an 
expression but want to keep the original expressions for historical purposes. 


Comments in AutoLISP programs are typically denoted with the use of a semicolon and are 
referred to as the single-line comment style. Expressions and text to the right of the semicolon 
are not executed; this allows you to add comments on a line by themselves or even after an 
AutoLISP expression. 

The following example demonstrates the use of the single-line comment style to add com- 
ments that explain the purpose of a function or what the expressions in the function are used 


for: 


? 


pi 
pi 


2 


3; Createlayer function creates/modifies a layer and 


expects two argument values. 
Arguments: 
name - A string that represents the name of the layer to create or modify 


color - A numeric value (1 - 255) that represents the color of the layer 


Usage: (createlayer "Doors" 2) 


(defun createlayer (name color / ) 


) 


The single-line comment style can also be used after an AutoLISP expression. The following 
demonstrates the use of comments after or before an AutoLISP expression: 


; Check to see if the layer exists before creating/modifying it 
(if (= (tblsearch "layer" name) nil) 

(command "._-layer" "_m" name "_c" color "" "") 

(setvar "clayer" name) 


(defun c:drawplate ( / ptl pt2 pt3 pt4) 


; Create the layer named Plate or set it current 
(createlayer "Plate" 5) 
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; Set the coordinates to draw the rectangle 
(setq pt1 '(0 0 @)) ; lower-left corner 
(setq pt2 '(5 0 @)) ; lower-right corner 
(setq pt3 '(5 2.75 0)) 3 upper-right corner 
(setq pt4 '(0 2.75 0)) 3 upper-left corner 


; Draw the rectangle 
(createrectangle pt1 pt2 pt3 pt4) 


; Display message to the user 
(prompt "\nRectangle drawn.") 
) 


In the previous example, all of the comments provide information about an individual or 
set of AutoLISP expressions, with the exception of the last comment. The last comment is an 
AutoLISP expression that would normally be executed, but it won't be executed as part of the 
program because the expression is located to the right of the semicolon. This isn’t the same situ- 
ation with the comments placed after the AutoLISP expressions that define and assign values 
to the pt1, pt2, pt3, and pt4 user-defined variables since the semicolon is placed after each 
expression. 

Although most comments will fit on a single line, there will be times when you might want 
to have a comment that spans more than one line. Such is the case with the comments that were 
shown before createlayer. Long comments that span multiple lines are often broken up into 
individual comments for readability, but this does require you to break a long line and place a 
semicolon in front of each individual line. However, there is a second comment style that you 
can use with longer comments or even inside an AutoLISP expression that might start and end 
on the same line. This second comment style is known as inline. 

The inline comment style starts and ends with a semicolon but also requires two pipe sym- 
bols ( | ), which are used to mark the beginning and end of the comment. Unlike the use of the 
semicolon by itself, which affects all the text after it on the same line, the expressions and text 
inside an inline comment are not executed but anything after it will be. 

The following demonstrates the use of both the inline comment style and the single-line 
comment style: 


3 | 
Createlayer function creates/modifies a layer and 
expects two argument values. 


Arguments: 
name - A string that represents the name of the layer to create or modify 
color - A numeric value (1 - 255) that represents the color of the layer 


Usage: (createlayer "Doors" 2) 
l; 
(defun createlayer (name color / ) 
; Check to see if the layer exists before creating/modifying it 
(if (= (tblsearch "layer" name) nil) 
(command "._-layer" "_m" name "_c" color "" "") 
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(setvar "clayer" name) 


(defun c:drawplate ( / ptl pt2 pt3 pt4) 
; Create or modify the layer named Plate 
(createlayer "Plate" 5) 


; Set the coordinates to draw the rectangle 


(setq pt1 '(0 © 0) ;| lower-left corner |; ) 
(setq pt2 '(5 © 0) ;| lower-right corner |; ) 
(setq pt3 '(5 2.75 0) ;| upper-right corner |; ) 
(setq pt4 '(0 2.75 0) ;| upper-left corner |; ) 


; Draw the rectangle 
(createrectangle pt1 pt2 pt3 pt4) 


; Display message to the user 
(prompt "\nRectangle drawn.") 


NOTE Single-line and inline comments are the primary comment styles used in a LSP file, but 
the Visual LISP Integrated Development Environment (VLIDE) does support a few additional 
comment styles. I discuss these comment styles in Chapter 11. 


Undefining and Redefining Standard AutoCAD 
Commands 


When you create custom functions, they typically introduce new functionality. However, you 
can also disable or override the functionality of a standard AutoCAD command using the 
undefine and redefine commands. When undefining commands, you want to make sure 
that you document this properly, as it can affect scripts, AutoLISP programs, menu macros, 
and much more. The documentation that you create should include comments in the LSP file 
that redefines the command, along with external documentation such as a ReadMe or Help file 
related to your custom programs. 

The following example creates a user-defined function named explode, which prevents 
users from exploding a hatch or dimension object, and then undefines the standard AutoCAD 
explode command using the undefine command: 


; Create a new Explode function 
(defun c:explode ( / ss) 
; See if Pick First is enabled and if so, get the current objects 
(if (> (getvar "pickfirst") 0) 
(setq ss (ssget "_I" '((-4 . "<OR")(O . "INSERT") (0 . "POLYLINE") 
(© . "LWPOLYLINE") (-4 . "OR>")))) 
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; If objects were not selected, prompt now 
(if (= ss nil) 
(setq ss (ssget '((-4 . "<OR")(0 . "INSERT") (0 . "POLYLINE") 
(© . "LWPOLYLINE")(-4 . "OR>")))) 


; Use current implementation of the Explode command 
(initcommandversion 2) 


; If objects were selected, explode them 
(if (/= ss nil) 
(command "._explode" ss "") 


(princ) 


) 


3; Undefine the Explode command 
(command "._undefine" "explode") 


A command is undefined in a drawing while it remains open after the use of the undefine 
command; the standard functionality of a command is restored when a drawing is created or 
opened. You can use the redefine command to restore an undefined command while a draw- 
ing remains open. Here is an example statement that restores the standard explode command, 
which was undefined in the previous example: 


(command "._redefine" "explode") 


Defining a Startup Function 


In AutoLISP you can define a special function named s: : startup. This function is executed 
when you create or open a drawing in AutoCAD, as long as it has been defined in a loaded LSP 
file. Although more than one LSP file can contain an s: : startup function, only the last loaded 
definition of the function is retained. The s: : startup function is typically used to initialize 
system variables, insert title blocks, or draw and modify objects in the current drawing upon 
opening. 

Here is an example of the s: : startup function: 


(defun s::startup ( / old_attreq) 
(setvar "osmode" 39) ; END, MID, CEN, and INT 
(setvar "pickfirst" 1) 


; Create layer for title block 
(command ",_-layer" "om" "titleblk" we "7" "u iry 


; Insert title block at 0,0 
(setq old_attreq (getvar "attreq")) 
(setvar "attreq" 0) 
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(command "._insert" "tb-c_size" "0,0" "1" "1" "@") 
(setvar "attreq" old_attreq) 


; zoom to extents 
(command "._zoom" "_e") 


Loading AutoLISP Files 


AutoLISP programs that are stored in a LSP file must be loaded into AutoCAD before they can 
be used. A number of methods can be used to load a LSP file. These fall into one of two catego- 
ries: manual or automatic. Most LSP files are loaded using one of the manual techniques. 


Manually Loading an AutoLISP File 


AutoCAD is a graphics- and resource-intensive application, and it loads components into mem- 
ory only as each is needed. LSP files are typically rather small in size, but loading a large num- 
ber of them into AutoCAD can impact performance. For this reason, you should load a LSP file 
only as it is needed. Once a LSP file is loaded into memory, it is not removed from memory until 
you close AutoCAD or the drawing from which the LSP file was loaded. 

Use the following techniques to manually load a LSP file into AutoCAD: 


Load/Unload Applications Dialog Box (appload Command) The Load/Unload 
Applications dialog box allows you to browse to where your LSP files are stored and select 
which files you want to load. After selecting a LSP file, you click Load to load the file into 
memory. I explain how to load a LSP file with the Load/Unload Applications dialog box in 
the “Using the Load/Unload Applications Dialog Box to Load a LSP File” section later in this 
chapter. 


Drag and Drop (Windows Only) LSP and other types of files can be dragged and dropped 
onto either the application or drawing windows of AutoCAD on Windows. When you drop 

a LSP file onto an open drawing window, AutoCAD loads the LSP file into memory for that 
drawing only. 


AutoLISP load Function The AutoLISP load function allows you to load a LSP file from a 
script file, from a command macro defined in a CUI/CUIx file, at the AutoCAD Command 
prompt, or even from another LSP file. When you use the load function, it searches the paths 
that are listed under the Support File Search Path node in the Options dialog box (Windows) 
or Application Preferences dialog box (Mac OS). You should avoid using absolute file paths 
with the Load function; if your drive mappings or folder structure change, the LSP file will 
fail to load. 


TIP The load function can be used in a menu macro—applied to a ribbon or toolbar button on 
Windows or a toolset button or menu item on Mac OS—to load a LSP file and start a function from 
the AutoCAD user interface. I explained how to customize the user interface in AutoCAD Platform 
Customization: User Interface and Beyond, Chapter 5, “Customizing the AutoCAD User Interface for 
Windows’ and Chapter 6, “Customizing the AutoCAD User Interface for Mac.” 
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The following is an example of loading a LSP file named utility. 1lsp with the load 
function: 


(load "utility.lsp") 


NOTE LSP files that are loaded using one of the manual techniques described here are loaded 
only into the current drawing. You must load the LSP file into each and every drawing file where 
you want to use it. However, you can use the vl- load-all function to load a LSP file into all 
open and subsequently opened drawings for the current AutoCAD session. 


Automatically Loading an AutoLISP File 
Manually loading LSP files doesn’t always create the best user experience, especially if you want 
certain functions to be available in each drawing file that is opened or created. Keep in mind, 
though, you don’t want all of your LSP files to be loaded at startup because it takes away some 
of the computing resources from the operating system and AutoCAD. 

You can use the following techniques to automatically load a LSP file into AutoCAD: 


Startup Suite—(appload Command) The Startup Suite is part of the Load/Unload 
Applications dialog box (appload command). When a LSP file is added to the Startup Suite, 
the file is loaded after a drawing is opened. Removing a file from the Startup Suite causes 
the file not to be loaded in any future drawings that are opened but does not unload it from 
any drawing files that the LSP file was loaded into during the current session. If you want 

to use the Startup Suite to load LSP files, you must add the files to the Startup Suite on each 
workstation and AutoCAD user profile. I discuss how to add LSP files to the Startup Suite in 
the “Using the Load/Unload Applications Dialog Box to Load a LSP File” section later in this 
chapter. 


Specific File Naming When you start AutoCAD or open a drawing, LSP files with specific 
names are automatically loaded if they are found in the support file search paths. Table 10.1 
lists the filenames and order in which these files are loaded into AutoCAD (files are listed in 
the order they are loaded by AutoCAD; acad.rx is loaded first and then on down the list). 


In addition to the files listed in Table 10.1, the LSP files you added to the Startup Suite in the 
Load/Unload Applications dialog box are loaded after each MNL file with the same name as 
a CUI/CUIx file being loaded into AutoCAD. After the files in the Startup Suite are loaded, 
the function (s::startup) is executed. The last file that is executed is the script file that is 
loaded with the /b or -b command-line switch. You learned about command-line switches 
in AutoCAD Platform Customization: User Interface and Beyond, Chapter 4, “Manipulating the 
Drawing Environment.” 


TABLE 10.1: Automatically loaded LSP files 
FILENAME DESCRIPTION 


acad.rx Lists each ObjectARX application (ARX) file that should be loaded. This file is 
not created by default; it is a file that you must create. Most ARX files are 
loaded on demand using special entries in the Windows Registry or property 
list (Plist) files on Mac OS. 
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TABLE 10.1: Automatically loaded LSP files (CONTINUED) 


FILENAME 


acad<release>. lsp 


acad.lsp 


acad<release>doc.lsp 


acaddoc. lsp 


<filename>.mnl 


DESCRIPTION 


A release-specific LSP file that is loaded once per AutoCAD session, at startup. 
<release> is a value that represents the release of AutoCAD. For example, 
AutoCAD 2015 looks for the file named acad2015.1sp, AutoCAD 2014 looks 
for the file named acad2014.lsp, AutoCAD 2013 looks for the file named 
acad2013.lsp, andso on. 


ALSP file that is loaded once per AutoCAD session, at startup. If the 
acadlspasdoc system variable is set to 1, the file is loaded with each drawing 
just like acaddoc. Lsp. The acad. lsp file must be created if you want to use it 
since it is not part of the AutoCAD installation. I discussed how to create a 
LSP file in the “Creating an AutoLISP File” section earlier in this chapter. 


Arelease-specific LSP file that is loaded with each drawing file that is opened. 
<release> is a value that represents the release of AutoCAD. For example, 
AutoCAD 2015 looks for the file named acad2015doc.lsp, AutoCAD 2014 
looks for the file named acad2014doc . Lsp, AutoCAD 2013 looks for the file 
named acad2013doc.lsp, and so on. 


ALSP file that is loaded with each drawing file that is opened. The file 
acaddoc. lsp must be created if you want to use it since it is not part of the 
AutoCAD installation. 


MNL files are associated with CUI/CUIx files that are used to define the 
AutoCAD user interface. When a CUI/CUIx file is loaded, AutoCAD looks for 
an MNL file with the same name and loads it if found. MNL files are loaded in 
the same order that CUI/CUIx files are. CUI/CUIx files are loaded in the order 
of partial files to the Main CUI/CUIx file, Main CUI/CUIx file, partial files to 
the Enterprise CUI/CUIx file, and then the Enterprise CUI/CUI file. 


NOTE On Windows, LSP files can also be loaded when a CUI/CUIx file is loaded. When a CUI/ 
CUIx file is being edited with the Customize User Interface Editor (Cui command), you can add 
LSP files to the LISP Files node. 


AutoLISP autoload Function The AutoLISP autoload function allows you to load a LSP 
file based on the use of a function defined with the C: prefix in the file. When you use the 
autoload function, it searches the paths that are listed under the Support File Search Path 
node in the Options dialog box (Windows) or Application Preferences dialog box (Mac OS) 
for the LSP file and then loads the file before executing the function. You should avoid using 
absolute file paths with the autoload function, because if your drive mappings or folder 
structure change, the LSP file will fail to load. The expressions that use the autoload func- 
tion should be loaded at startup. Consider adding these expressions to a LSP file and loading 
the file using a file like acaddoc. Lsp or an MNL file. 
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Oe 


The following is an example that loads a LSP file named maincmds.1sp with the autoload 
function when either the drawrectangle, drawcircle, loadlayers, or inserttitleblock 
function is typed at the Command prompt by the user: 
(autoload "maincmds" '("drawrectangle" "drawcircle" "lLoadlayers" 
"inserttitleblock") ) 


Plug-in Bundles Plug-in bundles allow you to load LSP and other custom files in AutoCAD 
2013 or later. A plug-in bundle is a folder structure with a special name and metadata file 
that describes the files contained in the bundle. I discuss plug-in bundles in the “Defining a 
Plug-in Bundle” section later in this chapter. 


Using the Load/Unload Applications Dialog Box to Load a LSP File 
The Load/Unload Applications dialog box (appload command) is the easiest way to load a LSP 
file into AutoCAD on Windows or Mac OS. Many of the other methods provide better integra- 
tion into a user’s workflow, but they require you to define where the LSP files are located. I 
describe in the next section how to set up and identify the folders AutoCAD should look in for 
custom files. 

The following steps explain how to load the mylisp. lsp file that you created in the “Creating 
an AutoLISP File” section earlier. 


NOTE Ifyou did not complete the steps in the “Creating an AutoLISP File” section, you can use 
the ch10_mylisp_complete. lsp file that is part of the samples files for this book (available 
from this book’s web page at www. Sybex. com/go/autocadcustomization) that you copied 
to a folder named MyCustomFi les in your Documents (or My Documents) folder. Once the 
sample file is stored on your system, remove the characters ch10_ from the filename. If you 
placed the sample files in a different folder, you will need to make the appropriate changes to 
the file selected in step 2. 


1. Do one of the following: 


@ On the ribbon, click the Manage tab > Customization panel > Load Application 
(Windows). 


@ On the menu bar, click Tools > Load Application (Mac OS). 
@ At the Command prompt, type appload and press Enter (Windows and Mac OS). 


2. When the Load/Unload Applications dialog box (see Figure 10.2) opens, browse to the 
MyCustomF7 les folder and select the mylisp. lsp file. Click Load. 


TIP Ifthe Add To History check box is selected when you click Load, AutoCAD adds the selected 
file to a list box on the History tab. Click the History tab and then select the file you want to 
load. Then click Load to load the file. 


3. If the File Loading - Security Concern message box is displayed, click Load. You'll learn 
which paths contain custom files that should be trusted in the “Identifying Trusted 
Locations” section and the sidebar “Restricting Custom Applications” later in this chapter. 


4. Click Close to return to the drawing area. 
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At the Command prompt, type msg and press Enter. A message box with the text First 
AutoLISP file is displayed (see Figure 10.1). 


Click OK to close the message box. 


Press F2 on Windows or Fn-F2 on Mac OS. You should see the message Version 1.0 - 
My AutoLISP Programs displayed in the command-line window. 
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8. Create a new drawing. 


9. At the Command prompt, type msg and press Enter. The message Unknown command 
"MSG". Press F1 for help. is displayed. 


NOTE | Ifyouare using AutoCAD 2014 or later, typing msg in step 9 might start the mspace or anoth- 
er command. If you don't see the Unknown command message, you will need to disable AutoCorrect. 
To disable AutoCorrect, at the AutoCAD Command prompt type - inputsearchoptions and press 


Enter. Then type r and press Enter. Type n and press Enter twice. Repeat step 9 and you should see 
the expected results. 


You can use the following steps to add the LSP file named mylisp. lsp to the Startup Suite 
you created in the “Creating an AutoLISP File” section. 


1. Do one of the following: 


> @ On the ribbon, click the Manage tab > Customization panel > Load Application 
(Windows). 


@ On the menu bar, click Tools > Load Application (Mac OS). 


@ Atthe Command prompt, type appload and press Enter (Windows and Mac OS). 


2. When the Load/Unload Applications dialog box opens, in the Startup Suite section, click 
Contents. 


3. When the Startup Suite dialog box (see Figure 10.3) opens, click Add (Windows) or + 


(Mac OS). 
FIGURE 10.3 
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4. Inthe Add File to Startup Suite dialog box, browse to the MyCustomFi les folder and 
select the my lisp. lsp file. Click Open. 


5. In the Startup Suite dialog box, click Close. 
6. Inthe Load/Unload Applications dialog box, click Close. 


7. At the Command prompt, type msg and press Enter. A message box with the text First 
AutoLISP file is displayed. 


8. Click OK to close the message box. 
9. Create anew drawing. 


10. At the Command prompt, type msg and press Enter. A message box with the text First 
AutoLISP file is displayed. This is expected because the mylisp. lsp file is loaded into 
the new drawing as a result of being added to the Startup Suite. 


11. Click OK to close the message box. 


Managing the Locations of AutoLISP Files 


The LSP files that you create or download from the Internet can be placed in any folder on your 
local or network drive. I recommend placing all your custom LSP files in a single folder on a 
network drive so they can be accessed by anyone in your company who might need them. You 
might consider using the name LSP Files or AutoLISP Files for the folder that contains your 
LSP files. 

I also recommend marking any folder(s) that contains custom files on the network as read- 
only for everyone except for those designated to make updates to the files. Marking the folders 
as read-only helps prevent undesired or accidental changes. Chapter 10, “Using, Loading, and 
Managing Custom Files,” in AutoCAD Platform Customization: User Interface and Beyond, dis- 
cussed file management. 

Regardless of which folder name you use or where you choose to place your LSP files, you 
need to let AutoCAD know where these files are located. To do so, add each folder that contains 
LSP files to the Support File Search Path and Trusted Locations settings of the Options dialog 
box (Windows) or Application Preferences dialog box (Mac OS). 


NOTE The following sections assume you have created a folder named MyCustomFi Les in the 
Documents (or My Documents) folder for the exercises and sample files that are part of 
this book. (If you haven't already, you can download the files from www. sybex. com/go/au- 
tocadcustomization.) If you placed the sample files in a different folder or are using your 
own folder, select that folder instead when prompted to browse to a folder as part of the steps. 


Specifying Support File Search Paths 

The support file search paths are used by AutoCAD to locate custom files, such as those that 
contain block definitions, linetype patterns, and AutoLISP programs. Use the Options dialog 
box on Windows and the Application Preferences dialog box on Mac OS to add the folders that 
contain LSP files to the support file search paths of AutoCAD. 
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The following steps explain how to add the folder named MyCustomFi les to the support file 
search paths used by AutoCAD: 


1. 


Click the Application menu button > Options (or at the Command prompt, type options 
and press Enter). 


2. When the Options dialog box opens, click the Files tab. 


3. Select the Support File Search Path node. Click Add and then click Browse. 


4. In the Browse For Folder dialog box, browse to the MyCustomFi les folder that you created 


5. 
6. 


for this book in the Documents (or My Documents) folder, or browse to the folder that con- 
tains the LSP files. 


Select the folder that contains your LSP files and click OK. 
Click OK to save the changes to the Options dialog box. 


If you are using AutoCAD on Mac OS, use these steps: 


1. 


ve WON 


On the menu bar, click AutoCAD <release> > Preferences (or at the Command prompt, 
type options and press Enter). 


When the Application Preferences dialog box opens, click the Application tab. 
Select the Support File Search Path node. 
Near the bottom of the dialog box, click the plus sign (+). 


In the Open dialog box, browse to the MyCustomF7 les folder that you created for this 
book in the Documents folder, or browse to the folder that contains the LSP files. 


Select the folder that contains the LSP files and click Open. 
Click OK to save the changes to the Application Preferences dialog box. 


You can edit an existing folder in the Options or Application Preferences dialog box by 
expanding the Support File Search Path node and selecting the folder you want to edit. After 
selecting the folder to edit, click Browse in Windows or double-click the folder on Mac OS, and 
then select the new folder. 


TIP = Youcan test to see whether AutoCAD can locate a file that might be in the support file search 
paths by using the AutoLISP findfile function. For example, type (findfile "mylisp 
lsp") at the AutoCAD Command prompt to see if the file named mylisp. Lsp is in one of 
the support file search paths. The location of the file is returned if it is found or ni l if the file 


is not found. 


It is possible with AutoLISP to get a listing of which folders have been added to the Support 
File Search Paths setting using the acadprefix system variable. The acadprefix system vari- 
able can return a listing of folders, but it doesn’t allow you to update which folders should be 
used. However, you can use the ACAD environment variable to update which folders are used. 

The following code shows an example of adding a folder named lsp files (which is at the 
root level of the C: drive on Windows) to the support file search paths using the ACAD environ- 
ment variable: 


(setenv "ACAD" (strcat (getenv "ACAD") ";c:\\lsp files;")) 
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If you are using AutoCAD on Mac OS, the same sample would look like this: 
(setenv "ACAD" (strcat (getenv "ACAD") ";/lsp files;")) 


You must place a semicolon before the location you are adding; including a semicolon after 
the location is not required. Typically, a semicolon is provided by AutoCAD after the last loca- 
tion, but you should check to see whether there is one. If you add the location with a semicolon 
before the path and a semicolon is provided by AutoCAD, resulting in back-to-back semicolons, 
the second semicolon is removed by AutoCAD. 


NOTE If the location added with the ACAD environment variable is invalid, AutoCAD doesn’t 
remove the invalid location. You might receive a message when you make changes to the Options 
or Application Preferences dialog box. Although it is possible to add the same location more 
than once with the ACAD environment variable, AutoCAD removes the duplicate entries in 
most cases. You should avoid adding duplicate locations, since it can increase the time it takes 
AutoCAD to locate a file. 


Identifying Trusted Locations 

If you are using AutoCAD 2013 SP1 or later on Windows or AutoCAD 2014 on Mac OS, when 
you try to load a LSP file, AutoCAD checks to see if that LSP file is being loaded from a trusted 
location. A folder that you identify as a trusted location contains LSP files that are safe to be 
loaded without user interaction. Any LSP file that isn’t loaded from a trusted location results in 
the File Loading - Security Concern message box (see Figure 10.4) being displayed. 


FIGURE 10.4 
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The File Loading - Security Concern message box indicates why it might not be a good idea 
to load the file if its origins aren’t known. While the message box is displayed, the user can 
decide to either load or not load the file that AutoCAD is attempting to load. When adding new 
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trusted locations, you want to make sure you limit the number of folders you trust, and those 
that are trusted should be marked as read-only to avoid the introduction of unknown LSP files 
to the folders. For more information on trusted paths, see the trustedpaths system variable in 
the AutoCAD Help system. 


NOTE A folder that you identify as a trusted location must also be listed in the Support File 
Search Paths setting of the Options or Application Preferences dialog box. 


The following steps explain how to add the folder named MyCustomFi les to the trusted loca- 
tions that AutoCAD can use to safely load LSP and other custom programs. 


1. 


Click the Application menu button > Options (or at the Command prompt, type options 
and press Enter). 


When the Options dialog box opens, click the Files tab. 


3. Select the Trusted Locations node and click Add, and then click Browse. 


4. In the Browse For Folder dialog box, browse to the MyCustomF7 les folder that you created 


7. 


for this book in the Documents (or My Documents) folder, or browse to the folder that con- 
tains your LSP files. 


Select the folder that contains your LSP files and click OK. 


If the selected folder is not marked as read-only, the Trusted File Search Path - Security 
Concern dialog box is displayed. Click Continue to add the folder. 


Click OK to save the changes to the Options dialog box. 


If you are using AutoCAD on Mac OS, use these steps: 


1. 


At the AutoCAD Command prompt, type (setq mydocs (getvar "mydocumentsprefix") ) 
and press Enter. The location of the My Documents folder is assigned to the user-defined 
variable mydocs. 


At the Command prompt, type (setq trustedpath (strcat mydocs "/ 
MyCustomFiles/") ) and press Enter. The path to the MyCustomFi les folder is assigned to 
the user-defined variable trustedpath. Use a different folder name or location here if the 
LSP files are stored in a different folder. 


At the Command prompt, type (setq trustedpaths (strcat (getvar "trusted- 
paths") "5" trustedpath ";")) and press Enter. The path you provided and those 
that are already trusted are appended together and assigned to the user-defined variable 
trustedpaths. 


At the Command prompt, type (setvar "trustedpaths" trustedpaths) and press 
Enter. The paths in the user-defined variable trustedpaths are assigned to the 
trustedpaths system variable. 


You can also use these steps for adding a trusted location in AutoCAD on Mac OS with 
AutoCAD on Windows. Instead of using forward slashes in step 2, use two backward slashes to 
be consistent with the value returned by the mydocumentsprefix system variable in step 1. For 
step 2, you would type (setq trustedpath (strcat mydocs "\\MyCustomFiles\\") ). 
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TIP You can test to see whether AutoCAD can locate a file in a trusted location by using the 
AutoLISP findtrustedfile function. For example, type (findtrustedfile "mylisp 
- Usp") at the AutoCAD Command prompt to see if the file named mylisp. lsp is ina trusted 
location and the AutoCAD support file search paths. The location of the file is returned if it is 
found or nil if the file is not found. 


RESTRICTING CUSTOM APPLICATIONS 


Starting with AutoCAD 2013 SP1, Autodesk introduced some new security measures to help reduce 
potential threats or viruses that could affect AutoCAD and the drawing files you create. These 
security measures allow you to do the following: 


@ Disable the loading of executable code when AutoCAD is started using the /nolisp (AutoCAD 
2013 SP1 on Windows), /safemode (AutoCAD 2014 on Windows), or -safemode (AutoCAD 
2014 on Mac OS) command-line switch. 


@ Automatically load and execute specially named files: acad. lsp, acad. fas, acad.vlx, 
acaddoc. lsp, acaddoc. fas, acaddoc. vx, and acad.dvb. 


In AutoCAD 2014, you can use the secureload system variable to control whether AutoCAD will 
load files only from trusted locations or allow you to load custom files from any location. I recom- 
mend setting secureload to 2 and loading custom files only from a secure and trusted location. 
However, the default value of 1 for secureload is also fine since it displays a message box when 
AutoCAD tries to load a file from a nontrusted location. Don’t set secure load to 0, thereby dis- 
abling the security feature, because it could result in your system loading a malicious program. 


Deploying AutoLISP Files 


Deployment is the process or processes used to allow others to access the LSP and custom files 
that you create. You might only need to worry about getting your files into the hands of those 
working at your company, but you might also want to send your files out to the subcontractors 
that your company works with. Sharing your custom files with subcontractors can help shorten 
turnaround times and makes it easier to share drawings back and forth. 

Deploying custom programs internally and externally are similar processes, but you may 
encounter some issues. Here are some issues that you need to consider when you are ready to 
deploy LSP files to others, either internally or externally: 


Locating Any file or folder paths used in your LSP files should be dynamic and not static. 
Never assume that there will always be a C drive or a specific network drive and folder 
structure on the workstation on which the LSP files will be loaded. Your programs should 
be designed to look for any files it needs as part of the Support File Search Path setting in 
the Options or Application Preferences dialog box. You learned how to add a folder to the 
Support File Search Path setting in the “Managing the Locations of AutoLISP Files” section 
earlier in this chapter. 
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Naming Autodesk recommends, although it is completely optional, adding a unique pre- 
fix to the beginning of your custom functions, even to global variables. This unique prefix 
will help you avoid potential conflicts when your LSP files are loaded into AutoCAD ona 
workstation that could have unknown custom programs loaded as well. For example, I use 
hypr_ as my prefix of choice (it’s a shortened version of HyperPics). A function name of 
c:drawplate would become c:hypr_drawplate. You could then create a custom (CUI/CUIX) 
file that adds your functions to the user interface or an alias-like LSP file that makes it easier 
to access your functions. Though not necessary—nor does it stop others from using your 
prefix—you can register the prefix you want to use at usa. autodesk. com/adsk/servlet/ 
index?id=1075006&siteID=123112. 


Testing Testing is a must when you begin deploying your files. I can’t overemphasize how 
important testing is when you deploy your LSP files. You want to make sure your programs 
execute as expected on various workstations running AutoCAD. I discuss some common 
testing techniques in Chapter 9, “Catching and Handling Errors.” 


Documenting Documentation is a key element you should consider providing for those 
who will install or use your LSP files. You should offer some basic documentation so end 
users understand the functions that are exposed. Explain how to resolve any common prob- 
lems they might have with your LSP files. I mention how to register help to custom functions 
in the “Implementing Help for Custom Functions” section later in this chapter. 


Distributing Make sure you have the rights to redistribute all support files that the LSP 
files might need. Typically, the only files that are commonly licensed are TrueType font 
(TTF) files, but licensing can extend to any files that you or your company have purchased or 
maybe even downloaded for free from the Internet. 


Updating Create a plan to keep files up to date. Updating is something you need to con- 
sider before you deploy your custom files the first time. 


Deployment Methods (Local vs. External) 

Releasing custom and LSP files to others in your company is often fairly straightforward 
because the files were developed around a set of known conditions; where files are located and 
which files are available is known, along with how AutoCAD was installed and configured. 
Internally, you can simply push your files to a location on the network and configure AutoCAD 
to look for the files there, as you learned earlier, in the “Managing the Locations of AutoLISP 
Files” section. 

Once you post the files, users can load them manually as they are needed, or you can use one 
of the methods from the section “Loading AutoLISP Files.” You can also create and post a CUI/ 
CUIx file for AutoCAD to load so that the user can load and access the functions in the LSP files 
without understanding how to load a LSP file. You learned about customizing the user interface 
in Chapters 5 and 6 of AutoCAD Platform Customization: User Interface and Beyond. 

Once a user can access and load the LSP files, I recommend providing basic instructions 
or even an informal training session to help them use the custom programs that you created. 
Making it as easy as possible for users to learn your custom programs will go a long way—it can 
mean the difference between a successful or a failed deployment. If users are confused, they are 
less likely to embrace the custom programs and the benefits they provide. 
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If you plan to deploy your custom programs to individuals outside your company, ask your- 
self the following questions: 


How will the user obtain your custom programs? Will you post them on a website or 
deliver them as an Autodesk® Exchange app that can be used with AutoCAD on Windows? 
Posting the files directly on a website does allow you to support both Windows and Mac OS. 


How will the user set up your custom programs? Ifa utility is free, users are usually a lit- 
tle more open to doing some work to get it recognized and loaded into AutoCAD. However, 
if you are expecting a user to pay for a program, their expectations change and you should 
consider using a plug-in bundle or creating an installer to make the deployment as easy and 
as error-free as possible. 


How will the user get help or support when there is a problem? A website is often the 
best solution when it comes to providing troubleshooting information or explaining how 
to use a program since it can be updated frequently. However, not all users have access to 
the Internet from their workstation. As shocking as it might be, it is not uncommon to have 
no connection or a limited connection at some companies. The level of support and docu- 
mentation that you provide should be a direct representation of how simple or complex a 
program is to learn, along with the fee you are charging. A simple program will commonly 
require far less documentation than one that offers a lot of functionality or is complex. 
Users often expect less documentation when a custom program is free compared to when 
they are paying for it. 


You can use one of three main methods to deploy your custom programs externally (or even 
internally): 


Manually A manual deployment is conducted when a user follows a detailed set of writ- 
ten instructions that explain how to set up the folder structure necessary for your custom 
program and then configures AutoCAD to look for the custom programs. After creating 

the folder structure and copying the files, the user commonly adds the necessary folders 

to the AutoCAD Support File Search Path and Trusted Locations settings, as explained 

in the “Managing the Locations of AutoLISP Files” section earlier in this chapter. Then 

they load the LSP files as necessary, as discussed in the “Loading AutoLISP Files” section. 
This approach is used frequently for many free AutoLISP programs found on the Internet. 
Although this is a low-cost approach, it can be error prone and is not ideal when the program 
needs to be set up on dozens of workstations. 


Plug-in Bundle A plug-in bundle is a folder structure that contains a manifest file that 
defines all the files making up the bundle and how AutoCAD should load the files within the 
bundle. A bundle can contain LSP, CUIx, MNL, help/documentation, and many other types 
of files. Because the manifest file tells AutoCAD how to load the files contained in the bundle, 
you don’t need to provide much in the form of instructions that explain how your custom 
programs need to be set up. To use a plug-in bundle, after you create the manifest file and set 
up the desired folder structure, you simply copy all folders and files that make up the bundle 
to the ApplicationAddins or ApplicationPlugins folder on each workstation the bundle 
should be available on. Plug-in bundles were first supported in AutoCAD 2013 on Windows 
and Mac OS, and you can develop them so that they work across multiple AutoCAD releases, 
AutoCAD-based products, and operating systems. You'll learn the basics of defining a plug- 
in bundle in the upcoming section, “Defining a Plug-in Bundle.” 
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Installer An installer provides you with a professional-looking front end that can auto- 
mate the same steps that a user might follow to manually set up your custom program. 

Many different types of applications are available that you can use to create an installer, 

such as InstallAware Studio, InstallShield, Setup Factory, and even Microsoft Visual Studio 
Professional or higher on Windows. If you are using Mac OS, you can use an application such 
as PackageMaker or Disk Utility. You can use an installer to copy and remove files related to 
a plug-in bundle, or you can design it to perform a variety of tasks that can help users con- 
figure AutoCAD. You can configure many installers to allow for maintenance releases or to 
provide a way for a user to upgrade an existing installation to a newer release. 


NOTE [If youare using any of the specially named files—such as acad. lsp or acaddoc. lsp— 
that AutoCAD looks for at startup to load your custom LSP files, you will need to figure out 
a different way to get them loaded before deploying the files outside your company. You don’t 
want to affect another company’s custom programs when they try to use your custom programs, 
so consider using a bundle plug-in or CUI/CUIx with/without an MNL file to get your LSP files 
loaded into AutoCAD. 


Defining a Plug-in Bundle 


A plug-in bundle, as I previously mentioned, is one of the methods that can be used to deploy 
your LSP files. Fundamentally, a bundle is simply a folder structure with its topmost folder hav- 
ing .bundle appended to its name and a manifest file with the filename PackageContents. xml 
located in the topmost folder. You can use Windows Explorer or File Explorer on Windows, or 
Finder on Mac OS, to define and name the folder structure of a bundle. The PackageContents 
.xml file can be created with a plain ASCII text editor, such as Notepad on Windows or TextEdit 
on Mac OS. 

The following is an example PackageContents. xml file that defines the contents of a bundle 
named DrawPlate. bundle that contains three files: a help file named DrawPlate.htm, and two 
LSP files named DrawPlate.lsp and Utility. tsp: 


<?xml version="1.0" encoding="utf-8"?> 

<ApplicationPackage 
SchemaVersion="1.0" 
AppVersion="1.0" 
Name="Plate Generator" 
Description="Draws a plate that is 5x2.75 starting at @0,0." 
Author="HyperPics, LLC" 
ProductCode="{3a5649b8-700e-4825-b505-77864e6edfb9 }¥" 
HelpFile="./Contents/DrawPlate.htm" 


<CompanyDetails 
Name="HyperPics, LLC" 
Url="http://www.hyperpics.com" 
/> 


<RuntimeRequirements 
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OS="Win32 |Win64|Mac" 

SeriesMin="R19.0" 

Platform="AutoCAD*" 

SupportPath="./Contents/" 
/> 


<Components Description="ALlL OSs"> 
<RuntimeRequirements 
OS="Win32 |Win64|Mac" 
SeriesMin="R19.0" 
Platform="AutoCAD*" 
SupportPath="./Contents/" 
/> 
<ComponentEntry Description="Main LSP file" 
AppName="DrawPlateMain" 
Version="1.0" 
ModuleName=""./Contents/DrawPlate.lsp"> 
</ComponentEntry> 
<ComponentEntry Description="Utility LSP file" 
AppName="UtilityFunctions" 
Version="1.0" 
ModuleName="". /Contents/Utility.lsp"> 
</ComponentEntry> 
</Components> 
</ApplicationPackage> 


The folder structure of the bundle that the PackageContents. xml file refers to looks like this: 


DrawPlate.bundle 
PackageContents. xml 
Contents 
DrawPlate.lsp 
DrawPlate.htm 
Utility.lsp 


I have provided the DrawPlate. bundle as part of the sample files for this book, but you will 
also learn how to create the DrawPlate. bundle yourself later in this chapter. To use the bundle 
with AutoCAD, copy the DrawPlate. bundle folder and all of its contents to one of the following 
locations so that all users can access the files: 


@ %ALLUSERSPROFILE%\Application Data\Autodesk\ApplicationPlugIns (Windows XP) 
@ %ALLUSERSPROFILE%\Autodesk\ApplicationPlugIns (Windows 7 or Windows 8) 
@ /Applications/Autodesk/ApplicationAddIns (Mac OS) 


If you want a bundle to be accessible only by a specific user, place that bundle into one of the 
following locations under that user’s profile: 


@ %APPDATA%\Autodesk\ApplicationPlugiIns (Windows) 
@ ~/Autodesk/ApplicationAddIns (Mac OS) 
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For additional information on the elements used to define a PackageContents. xml file, per- 
form a search in the AutoCAD Help system on the keyword “PackageContents.xml.” 


NOTE The appautoload system variable controls when bundles are loaded into AutoCAD. 
By default, bundles are loaded at startup, when a new drawing is opened, and when a plug- 
in is added to the ApplicationPlugins or ApplicationAddIns folder. You can use the 
appautoloader command to list which bundles are loaded or reload all the bundles that are 
available to AutoCAD. 


Implementing Help for Custom Functions 
Earlier in this chapter, I discussed the importance of using comments to document the AutoLISP 
expressions that make up your custom functions and AutoLISP programs. In addition to 
comments, when you create new functionality using AutoLISP you should create documenta- 
tion for the users; the importance of user documentation is often overlooked by developers. 
Documentation can range from being as basic as a few sentences to something that is much 
more comprehensive and explains how to use all the functions that are exposed as part of your 
LSP files when they are loaded. 

The AutoLISP help and setfunhelp functions are used to access the AutoCAD Help facility. 
Based on the release or platform on which you are developing, these functions support some or 
all of the following file types: 


@ HTM/HTML 

@ Plain ASCII text (TXT) 

@ Microsoft Help (CHM) - Windows only 
@ WinHelp (HLP) - Windows only 


The following shows the syntax for the AutoLISP help function: 
(help [filename [help_topic [chm_window_cmd]]]) 


Its arguments are as follows: 


filename The filename argument is a string that represents the name of the HTM, HTML, 
CHM, HLP, or TXT file that is to be opened by the AutoCAD Help facility. You must specify 
both the filename and path. This argument is optional, and AutoCAD opens the Help system 
if it is not provided. 


help_topic The help_topic argument is a string that represents the standard AutoCAD 
Help topic to open or the topic file to open when a CHM file is specified by the filename 
argument. This argument is optional and only used when a CHM file is specified. 


chm_window_cmd The chm_window_cmd argument is an integer used to control the behavior 
of the HTML Help window that is opened for a CHM file. This argument is optional and 
available only when a CHM file is specified. 


Here are some example expressions that demonstrate the use of the AutoLISP help function: 


; Opens the AutoCAD Help system with no topic 
(help) 
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; Opens the reference topic for the AutoCAD Rectang command 
(help "" "rectang") 


; Opens the specified URL in the system's default web browser 
(help "http: //www.sybex.com/go/autocadcustomization") 


; Opens a local HTML file on Windows 
(help "C:\\Program Files\\Autodesk\\AutoCAD 2015\\Help\\augi.htm") 


; Opens a local HTML file on Mac OS 
(help "/Applications/Autodesk/AutoCAD 2015/AutoCAD 
2015.app/Contents/Resources/ExtendedResources.htm") 


; Opens a CHM file named acadauto to the topic idh_lightweightpolyline_object 
(help "C:\\Program Files\\Common Files\\Autodesk Shared\\acadauto.chm" 
"jdh_lightweightpolyline_object") 


The following shows the syntax for the AutoLISP setfunhelp function: 
(setfunhelp function_name [filename [help_topic [chm_window_cmd]]]) 


Its arguments are as follows: 


function_name The function_name argument represents the user-defined function pre- 
fixed with C: with which you want to associate a help file or topic. 


filename The filename argument is a string that represents the name of the HTM, HTML, 
CHM, HLP, or TXT file that is to be opened by the AutoCAD Help facility. You must specify 
both the filename and path. This argument is optional, and AutoCAD opens the Help system 
if it is not provided. 


help_topic The help_topic argument is a string that represents the standard AutoCAD 
Help topic to open or the topic file to open when a CHM file is specified by the filename 
argument. This argument is optional and used only when a CHM file is specified. 


chm_window_cmd The chm_window_cmd argument is an integer used to control the behavior 
of the HTML Help window that is opened for a CHM file. This argument is optional and 
available only when a CHM file is specified. 


Here are some examples that demonstrate the use of the AutoLISP setfunhelp function. 
These examples are based on the existence of an AutoLISP function named c:drawplate. When 
the c:drawplate function is active or its name is entered at the Command prompt, the topic 
associated with the function is displayed when the user presses F1. 


; Launches the the AutoCAD help system with no topic 
(setfunhelp "c:drawplate") 


; Opens the reference topic for the AutoCAD Rectang command 
(setfunhelp "c:drawplate" "" "rectang") 


; Opens the specified URL in the system's default web browser 
(setfunhelp "c:drawplate" "http: //www.sybex.com/go/autocadcustomization") 


298 


CHAPTER10 AUTHORING, MANAGING, AND LOADING AUTOLISP PROGRAMS 


; Opens a local HTML file on Windows 
(setfunhelp "c:drawplate" 
"C:\\Program Files\\Autodesk\\AutoCAD 2015\\Help\\augi.htm") 


; Opens a local HTML file on Mac OS 
(setfunhelp "c:drawplate" "/Applications/Autodesk/AutoCAD 2015/ 
AutoCAD 2015.app/Contents/Resources/ExtendedResources.htm") 


; Opens a CHM file named acadauto to the topic idh_lightweightpolyline_object 
(setfunhelp "c:drawplate" 
"C:\\Program Files\\Common Files\\Autodesk Shared\\acadauto.chm" 
"jdh_lightweightpolyline_object") 


Exercise: Deploying the drawplate Function 


In this section, you will continue to work with the drawplate function that was originally 
introduced in Chapter 2, “Understanding AutoLISP.” You worked with the drawplate function 
in Chapter 9 and added error handling and undo grouping to the function. The key concepts I 
cover in this exercise are as follows: 


Identifying the Locations of Your LSP Files AutoCAD needs to know where your LSP files 
are so that it can locate them and know which locations are trusted. 


Loading a LSP File on Demand and by Reference AutoLISP files should be loaded only as 
they are needed whenever possible to help save on system resources. 


Connecting Custom Help Supporting basic help files is something many developers over- 
look, but this support can help give your programs a polished and professional look. Users 
also appreciate when there is some form of self-help that might aid them in solving a problem 
they are having or learning about a feature. 


Creating and Deploying Plug-in Bundles Plug-in bundles can make deploying AutoLISP 
programs easier than having to set up support file search paths and trusted locations on 
multiple machines, and it allows you to support multiple releases of a program with much 
greater ease. 


NOTE Thestepsin this exercise depend on the completion of the steps in the “Exercise: Handling 
Errors in the drawplate Function” section of Chapter 9. If you didn’t complete the steps, do 
so now or start with the ch10_drawplate. lsp and ch10_utility.lsp sample files avail- 
able for download from ww. sybex.com/go/autocadcustomization. You will also need the 
packagecontents.xml and drawplate.htm sample files. Place these sample files in 
the MyCustomFi les folder under the Documents (or My Documents) folder or in the location 
you are using to store the LSP files. Once you've stored the sample files on your system, remove 
the characters ch10_ from the name of each file. 


Loading the utility.lsp File by Reference 


When an AutoLISP program relies on the functions defined in another LSP file, it is common 
practice to use the load function to ensure that the functions in the LSP file are made available. 
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Up until now, you have been manually loading the utility. lsp file each time you wanted to 
use the functions that are defined in the file. 

The following steps explain how to load the utility. lsp file when drawplate. lsp is loaded 
into AutoCAD: 


1. Open the drawplate. lsp file in Notepad on Windows or TextEdit on Mac OS. 


2. In the text editor area, add the following before any other comments or AutoLISP expres- 
sions in the file: 


; Load the utility.lsp file 
(load "utility.lsp") 


3. Click File > Save. 


NOTE The load function can be used with a menu macro to load a LSP file from the AutoCAD 
user interface. 


Loading the drawplate.Isp File on Demand 
Loading all your AutoLISP programs at startup is an option using Load statements in a LSP file 
such as acad. lsp or acaddoc. Lsp, but you should load only the files when they are needed. The 
autoload function is a way to inform AutoCAD that you have a set of custom functions that are 
standing by and ready for use. Instead of using multiple Load statements in acad 
. Lsp or acaddoc. Lsp, I recommend using autoload statements to make your functions avail- 
able and load the associated LSP file upon the function’s first use. 

In these steps, you create a new LSP file named myautoloader . lsp that will load the 
drawplate. lsp file when the user enters drawplate at the Command prompt: 


1. Create a new LSP file named myautoloader. lsp with Notepad on Windows or TextEdit 
on Mac OS. 


2. Inthe text editor area of the myautoloader . Lsp file, type the following: 


; Demand loads the drawplate.lsp file 
(autoload "drawplate" '("drawplate") ) 


3. Click File > Save. 


NOTE Ifyour company doesn’t already have an acad. lsp file, you could rename myauto loader 
. Lsp to acad. Lsp and let AutoCAD load the file automatically. Use the statement (findfile 
"acad. lsp") to determine whether a file named acad . lsp already exists in the support file 
search paths of your AutoCAD installation. If nil is returned, AutoCAD couldn't locate an 
instance of the acad. lsp file. 


Enabling Help Support for the drawplate Function 


Providing basic help support for your programs can go a long way, especially if you leave the 
company someday or want to eventually sell your custom program. 
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In these steps, you enable contextual help for the drawplate function: 


1. 


3. 


Open the drawplate. lsp file in Notepad on Windows or TextEdit on Mac OS, if it isn’t 
open from the earlier exercise. 


In the text editor area, scroll to the end of the file and add a few blank lines. Add the fol- 
lowing to the end of the file: 


; Register the help file for F1l/contextual help support 
(setfunhelp "c:drawplate" (findfile "DrawPlate.htm") ) 


Click File > Save. 


Configuring the AutoCAD Support and Trusted Paths 


In order for the AutoLISP load and findfi le functions to locate the files for your custom pro- 
grams, AutoCAD needs to know where the files are located. To locate a custom file, AutoCAD 
uses the paths that have been added to the Support File Search Path and Trusted Locations set- 
tings in the Options dialog box (Windows) or the Application Preferences dialog box (Mac OS). 

The following steps explain how to add the folder named MyCustomF7 les to the support file 
search paths and trusted locations used by AutoCAD: 


1. 


Click the Application menu button > Options (or at the Command prompt, type options 
and press Enter). 


. When the Options dialog box opens, click the Files tab. 


3. Select the Support File Search Path node. Click Add and then click Browse. 


9. 
10. 


In the Browse For Folder dialog box, browse to the MyCustomF7 les folder that you created 
for this book in the Documents (or My Documents) folder, or browse to the folder that con- 
tains your LSP files. 


Select the folder that contains your LSP files and click OK. 


With the new path still highlighted, press F2. Press Ctrl+C, or right-click and choose 
Copy. 
Select the Trusted Locations node. Click Add. 


. With focus on the in-place text editor, press Ctrl+V, or right-click and choose Paste. Then 


press Enter to accept the pasted path. 
If the Trusted File Search Path - Security Concern message box appears, click Continue. 


Click OK to save the changes to the Options dialog box. 


If you are using AutoCAD on Mac OS, use these steps: 


1. 


2. 


On the menu bar, click AutoCAD <release> > Preferences (or at the Command prompt, 
type options and press Enter). 


When the Application Preferences dialog box opens, click the Application tab. 
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3. Select the Support File Search Path node. 
4. Near the bottom of the dialog box, click the plus sign (+). 


5. In the Open dialog box, browse to the MyCustomF7 les folder that you created for this 
book in the Documents folder, or browse to the folder that contains your customized files. 


6. Select the folder that contains your customized files and click Open. 


7. Click OK to save the changes to the Application Preferences dialog box. 


WARNING FExecutingthe AutoLISP expressionsin step 8 more than once willresult in the folder 
being added multiple times to the Trusted Locations setting. You should make sure the folder 
you are adding is not already listed as part of the trustedpaths system variable. I don’t know 
whether listing the folder more than once is a problem, but ideally you should not list the same 
folder multiple times. 


8. At the Command prompt, type (prompt (getvar "trustedpaths") ) and press Enter. If 
the MyCustomF7 les folder or the location of the drawplate. lsp file is listed, type one of 
the following and press Enter: 


(setq trustedpath (strcat (getvar "trustedpaths") "5" 
(vl-filename-directory (findfile "drawplate.lsp")) "/;")) 


or 


(setvar "trustedpaths" trustedpath) 


Testing the Deployment of the drawplate Function 
The time has come to put in motion everything that you have done up to this point. You have 
added statements that load the utility. lsp file from drawplate. lsp, defined an autoloader 
program, enabled contextual help for the drawplate function, and configured the support 
file search and trusted location paths. It is now time to see all of it in action. If all goes well, it 
will feel like you are hearing the climax of a movement being played by an orchestra. If some- 
thing doesn’t go right, you will have that meh moment, but don’t feel discouraged; we have all 
been there. 

The following steps explain how to use the load function to add the myautoloader. lsp file 
into AutoCAD from the Command prompt. Once it’s loaded, you will then start the drawplate 
function and test the help file with which it has been associated. 


1. At the Command prompt, type (load "myautoloader") and press Enter. 


If you see the error message ; error: LOAD failed: "myautoloader", make sure that 
the file was placed in the MyCustomF7 les folder and that the folder is part of the Support 
File Search Path setting. A return value of nil is expected by the load function. 


2. Type drawplate and press Enter. 


You should see the familiar Specify base point for plate or [Width\Height]: 
prompt. Remember, you didn’t load the drawplate. lsp or utility. lsp file yourself. You 
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simply loaded myautoloader. lsp and it loaded drawplate. lsp when you started the 
drawplate function. Upon loading, the drawplate.1sp file then loaded utility. lsp. 


3. With the drawplate function still active, press F1 on Windows or Fn-F1 on Mac OS. 


The custom help documentation associated with the drawplate function is shown. 
Figure 10.5 shows what the document looks like in the AutoCAD Help window on 
Windows. On Mac OS, the topic is opened in your system's default browser. 


FIGURE 10.5 b Autodesk AutoCAD 2014 - Help -5 
Custom help for a custom 
" <> Home > 
function . : 73 
DrawPlate Help 


This document is the Help for the DrawPlate function. 
Last Updated: 1/5/2014 


Created By: Lee Ambrosius 


DrawPlate (Command) 


File Required: DrawPlate.lsp 
Description: Draws a plate that is 5x2.75 units in size starting @0,0. 


To use the DrawPlate function, type its name at the AutoCAD Command prompt and press Enter. 


4. Press Esc to end the drawplate function. 


Creating DrawPlate.bundle 
Plug-in bundles are a relatively new concept in AutoCAD, but they make deploying your custom 
programs much easier. After all, a bundle is simply a folder structure that you can copy between 
machines no matter which operating system you are using. 

The following steps explain how to create a bundle named DrawPlate. bundle. 


1. On Windows, do one of the following: 


@ Launch Windows Explorer or File Explorer, depending on your version of the operating 
system. (Right-click the Windows Start button on Windows XP or Windows 7, or right- 
click in the lower-left corner of the screen on Windows 8. Click Windows Explorer or 
File Explorer.) 


@ Browse to the MyCustomFiles folder under the Documents (or My Documents) folder. 
Right-click in an empty area and choose New > Folder. 


2. On Mac OS, do one of the following: 
@ Launch Finder. (On the Desktop, click Go > Documents.) 


@ Browse to the MyCustomFiles folder under the Documents (or My Documents) folder. 
Click Settings (the gear icon) near the top center of the Finder window and choose 
New Folder. 
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3. Type DrawPlate.bundle and press Enter. 
4. Do one of the following: 
@ On Windows, double-click the DrawP late .bundle folder. 
@ On Mac OS, secondary-click DrawPlate. bundle and choose Show Package Contents. 


5. Create a new folder under the DrawPlate. bundle folder and name the new folder 
Contents. 


6. From the sample files that are available with this book and those that you created, copy 
the following files into the appropriate folder (see Table 10.2). 


TABLE 10.2: Files for DrawPlate. bundle 


FILENAME FOLDER 
packagecontents. xml DrawPlate. bundle 
utility.lsp Contents 
drawplate.lsp Contents 
drawplate.htm Contents 


Deploying and Testing the DrawPlate.bundle 
Plug-in bundles must be placed within a specific folder before they can be used. You learned 
which folders a bundle can be placed in earlier, in the section “Defining a Plug-in Bundle.” 

The following steps explain how to deploy a bundle named DrawPlate. bundle on Windows: 


1. In Windows Explorer or File Explorer, browse to the DrawPlate. bundle folder you cre- 
ated in the previous exercise. 


2. Select the DrawPlate. bundle folder and right-click. Choose Copy. 


3. In the Location/Address bar of Windows Explorer or File Explorer, type one of the fol- 
lowing and press Enter: 


@ On Windows XP, type SALLUSERSPROFILE%\Application Data\Autodesk\ 
ApplicationPlugIns. 


@ On Windows 7 or Windows 8, type %ALLUSERSPROFILE%\Autodesk\ 
ApplicationPlugins. 


4. Right-click in the file list and choose Paste. 
The following steps explain how to deploy a bundle named DrawPlate. bundle on Mac OS: 
1. In Finder, browse to the DrawPlate. bundle folder you created in the previous exercise. 


2. Select the DrawPlate. bundle folder and secondary-click. Choose Copy “DrawPlate. 
bundle.” 
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3. In Finder, click Go > Go To Folder, type /Applications/Autodesk/ApplicationAddIns, 
and click Go. 


4. Secondary-click in the files list and choose Paste Item. 

The following steps explain how to test DrawPlate. bundle: 

1. In AutoCAD, create a new drawing. 

2. At the Command prompt, type drawplate and press Enter. 


You should see the familiar Specify base point for plate or [Width\Height]: 
prompt. Before, you had to load the drawplate. lsp, utility. lsp, or myautoloader.lsp 
file to access the functionality. 


3. Press Esc to end the drawplate function. 


NOTE Ifthe drawplate function isn’t available in the drawing, check the current value of 
the appautoload system variable. The appautoload system variable controls when a bundle 
should be loaded. The default value of the appautoload system variable is 14, which indicates 
a bundle should be loaded at startup, when a new drawing is opened, or when a new bundle has 
been added to one of the plug-in folders. 


Chapter 11 


Using the Visual LISP Editor 
(Windows only) 


Up until now, when working with LSP files you have been using Notepad, which is designed 
primarily for creating and editing plain ASCII text files—not LSP files. The Autodesk® 
AutoCAD® program on Windows supports an integrated development environment (IDE) used 
to develop custom AutoLISP® applications. The IDE used to work with AutoLISP is called the 
Visual LISP® Editor and is often referred to as the VLIDE. Unlike Notepad, the Visual LISP 
Editor offers a range of tools that are designed specifically for working with LSP files. 

In this chapter, you'll learn how to create and manage LSP files with the Visual LISP Editor. 
You'll also learn how to format AutoLISP statements in the editor and debug a loaded program. 
After a program has been debugged, it can be compiled into an FAS or VLX file to prevent some- 
one from making changes to the original LSP file. 


NOTE If youare using Mac OS, I recommend installing Windows and AutoCAD on Boot Camp 
or Parallels so that you can use the Visual LISP Editor when creating or editing LSP files. 


Accessing the Visual LISP Editor 


You access the Visual LISP Editor from within AutoCAD by entering vlide at the Command 
prompt. You can also start the vLide command by clicking the Manage tab > Applications panel 
> Visual LISP Editor. Figure 11.1 shows the initial state of the Visual LISP Editor after the vlide 
command is started. 

The Visual LISP Editor is similar to many Windows-based applications. It has a menu bar 
displayed along the top with toolbars placed below it that allow access to many of the tools 
commonly used to create, format, and debug LSP files. The large area in the middle is where you 
access windows for editing open LSP files and other tool-related windows. 

When you display the Visual LISP Editor, any files not closed during the previous edit- 
ing session are reopened automatically. The reopening of files makes it easy to pick up where 
you left off working on custom programs. Along with previously opened files, the Visual LISP 
Console and Trace windows are also displayed in a minimized state near the bottom of the 
Visual LISP Editor. The Visual LISP Console and Trace windows might be hidden behind one of 
the other opened editor windows and can be brought to the foreground using the Window 
pull-down menu. 
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FIGURE 11.1 Search toolbar 
The Visual LISP ; 
Editor with a new View toolbar Tools toolbar 
LSP file open in an 
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Edit: -no file- (Visual LISP) L 00001 C 00001 


Trace window 


Managing AutoLISP Files with the Visual LISP Editor 


Creating new files in the Visual LISP Editor is similar to creating a new file in many other 
Windows-based programs. You create a new file by clicking the New button on the Standard 
toolbar or by choosing File > New File. The new file is a general text file and is not assigned a 
specific file extension, so the new file could be used to store custom linetype definitions, hatch 
patterns, or AutoLISP programs. An extension is added to the filename when it is saved the 
first time. 

You can save the file by clicking Save File on the Standard toolbar or by choosing File > Save 
or File > Save As. If the Save-as dialog box is displayed, you can specify a name and location for 
the file and append the desired file extension to the filename. As an alternative, you can choose 
a file format from the Save As Type drop-down list. Click Save to store the file to disk. Choose 
File > Save All to save any open and changed files back to disk. 

If you want to edit an existing file, click Open on the Standard toolbar or choose File > Open 
File. When the Open File To Edit/View dialog box is displayed, browse to and select the file you 
want to open, and then click Open. You can use the File Of Types drop-down list to filter the 
files that are displayed in the Files list. Choose File > Reopen and then an item from the menu to 
reopen a file that was previously opened. 


NOTE Choose File > Revert if you want to reload a file based on the content that is in the ver- 
sion of the file on disk instead of in memory. 


When you are done working with a file, save any changes and then click the Close button in 
the upper-right corner of the editor window or choose File > Close. Choose File > Close All to 
close all open files in the current editing session. 
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TIP Ifyou think you might want to continue to work with a LSP file later, leave it open in the 
Visual LISP Editor and simply close the editor without first closing the file. The next time the 
Visual LISP Editor is loaded, it reopens the file for you if it is found in its previous known 


location. 


As you work in the Visual LISP Editor, you can take advantage of the tools on the Edit and 
Search menus to assist in editing and finding code in the current editor window. Many of the 
available tools are similar to those found in Notepad, with the exception of the Parentheses 
Matching and Extra Commands options on the Edit menu. I’ll explain some of the items on 


these two submenus later in this chapter. 


Although the Visual LISP Editor offers many tools that differentiate it from Notepad, one 
of my favorite tools is the Apropos window (see Figure 11.2, on the left). The Apropos 
window allows you to obtain a listing of the AutoLISP functions and variables that are 
defined in the current drawing. Display the Apropos window by clicking Apropos on the 
View toolbar or by choosing View > Apropos Window. After the window is displayed, enter 
a text string that matches part of the function or variable names you want to list and click 
OK. The matching results are displayed in the Apropos Results window (see Figure 11.2, on 


the right). 
FIGURE 11.2 @ Apropos options 
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Formatting an AutoLISP File 


Editor formatting is one of the key advantages of using the Visual LISP Editor over Notepad. 
The Visual LISP Editor supports the following features that help you to author and format code: 


@ Color syntax 


Automatic indenting 


+ 
@ Ability to format code by selection or in the editor window 
+ 


Comments 
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Coloring Syntax 


The Visual LISP Editor supports color syntax, which helps to distinguish function names from 
argument values. Color is also used to help distinguish values based on the data type; strings 
are displayed in magenta, integers are displayed in green, and real numbers are displayed in 
teal. Many modern development environments, such as Microsoft Visual Studio, also support 
color syntax. Figure 11.3 shows the badcode function from Chapter 9, “Catching and Handling 
Errors,” open in the Visual LISP Editor. 


FIGURE 11.3 

Color syntax allows 
you to quickly 
identify functions, 
argument values, 
and problems ina 
program. 


s) Ch21_BadCode.lsp 
(defun c:BadCode ( 7 ) 
; Prompt for string 
{setq str (getstring 39) 


; If str is not nil, continue 
(if str 
(progn 
(princ 
\nUalue entered: 


\nEnter an integer: 
DEBUG: Ready to divide 


\nDivisor: 


DEBUG: IF ELSE 


DEBUG: Inside IF 


Although the color of the characters doesn’t come through in black and white, you should 
notice that the second statement shown in Figure 11.3 is a comment and its background is 
shaded to help you visually distinguish it from other statements in the program. When the 
Visual LISP Editor detects an error in the syntax within an open LSP file, the color syntax 
applied to code can be affected. The change in the color syntax indicates an error. 

In Figure 11.3, a quotation mark is missing from the (princ "DEBUG: Inside IF) statement. 
The missing quotation mark affects the color syntax of all the statements that are after it. Notice 
most of the statements after the missing quotation mark are also displayed in a gray color, such 
as the string of the (setq str (getstring "\nEnter a string: ")) statement. As you can 
see, color syntax can also be helpful in identifying problems in a program and thereby it reduces 
the amount of debugging that you have to perform. 

You can adjust the colors that the Visual LISP Editor applies to the editor window by choos- 
ing Tools > Window Attributes > Configure Current. In the Window Attributes dialog box 
(see Figure 11.4), click the element drop-down list and choose the element you want to format. 
Then select a foreground (top row) and background (bottom row) color to apply to the element. 
Choose Transparent FG or Transparent BG to match the background color of the editor window. 
Clear the Lexical Colors check box to remove the color from all text elements. 

You can also set the number of characters that a tab character represents and the left margin 
of the editor window (in pixels) by changing the values of the Tab Width and Left Margin text 
boxes in the Window Attributes dialog box. 
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FIGURE 11.4 o Window Attributes 
Setting element colors Text colors 
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Formatting Code 


Code formatting isn’t something you have to do; AutoCAD and AutoLISP don’t care whether 
all code is placed on a single line or is nicely formatted. Formatting code is a benefit for you, 
the programmer, because it makes code easier to read and helps you identify missing or extra 
parentheses. When writing code in Notepad, you have to manually add spaces and indents to 
make your code easier to follow. 

The Visual LISP Editor provides several features designed to format code as you type it in 
the editor window, or you can specify that you'd like to base the formatting on the code that 
was previously entered. When you start a statement by typing an opening parenthesis and then 
press Enter without adding the closing parenthesis on the same line, the Visual LISP Editor 
indents the next line to signal that the new line is a continuation of the current expression. You 
can specify the size of the indent with the Narrow Style Indentation value in the Format Options 
dialog box (see Figure 11.5). To open this dialog box, choose Tools > Environment Options > 
Visual LISP Format Options. 


FIGURE 11.5 @ Format options 
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In the Format Options dialog box, specify the settings for the Visual LISP Editor formatting 
tools. Click the More Options button to access additional formatting settings. Once the format- 
ting options are set, click Format Edit Window on the Tools toolbar or choose Tools > Format 
Code In Editor to format all the code in the current editor window. If you want to format only 
some of the code, select the code you want to format and click Format Selection on the Tools 
toolbar or choose Tools > Format Code In Selection. 


NOTE When you format all of the code in the editor window, the Visual LISP Editor will notify 
you if it finds a problem with a missing or extra parenthesis. 


Commenting Code 

Comments are commonly added by you as the programmer, as I explained in Chapter 10, 
“Authoring, Managing, and Loading AutoLISP Programs.” The Visual LISP Editor can for- 
mat the comments that have been added to an AutoLISP program based on the settings in the 
Format Options dialog box, and it can also add what are called form-closing comments. 

Form-closing comments are added after the closing parentheses of specific functions, such as 
defun, if, and progn. The comments let you know the location in the code of the closing paren- 
thesis for functions to assist you in the debugging of a program. Select the Insert Form-Closing 
Comment option and type the prefix for the comment in the Form-Closing Comment Prefix 
text box of the Format Options dialog box (choose Tools > Environment Options > Visual LISP 
Format Options). Form-closing comments are added when you use the Format Edit Window or 
Format Selection tool discussed in the previous section. 

In addition to adding form-closing comments, you can mark selected statements in the cur- 
rent window as comments. Select the statements to be marked as comments, and then click 
Comment Block on the Tools toolbar or choose Edit > Extra Commands > Comment Block. The 
Visual LISP Editor places three semicolons (; ; ;) in front of each of the selected statements. Click 
Uncomment Block or choose Edit > Extra Commands > Comment Block to uncomment selected 
statements. The Uncomment Block tool removes only the semicolons that are located at the left 
margin of the editor window—indented comments are ignored. 


Validating and Debugging Code 


The benefits of the Visual LISP Editor extend beyond being able to view code in color, use 
automatic formatting, and insert comments based on the way your code was written. Since the 
Visual LISP Editor was designed to be a proper development environment, it offers the follow- 
ing functionality that can be used to validate, load, and debug code: 


@ Execute AutoLISP statements without returning to the AutoCAD Command prompt 
@ Load and check the code ina LSP file 


@ Debug the code in the current editor window 


Executing Code from the Visual LISP Editor 

The Console window (see Figure 11.6) is an extension of the AutoCAD Command prompt; it 
allows AutoLISP statements to be executed in real time from the Visual LISP Editor. When 
you type an AutoLISP statement in the Console window and press Enter, the value of the 


VALIDATING AND DEBUGGING CODE] 311 


last evaluated function is returned to the Console window and not the AutoCAD Command 
prompt. AutoLISP statements entered in the Console window follow the same rules as state- 
ments entered at the AutoCAD Command prompt, with one exception: user-defined variables 
don’t need to be prefixed with an exclamation point to get the current value. 


FIGURE 11.6 
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The Console window is opened in a minimized state by default, but you can choose Window 
> Visual LISP Console to bring the window to the foreground. At the _$ prompt, type the state- 
ment you want to execute and press Enter. You can press Shift+Enter to move input to the next 
line, but the statements won't be executed until you press Enter. Right-click in the Console 
window to clear the window or to enable logging. 


NOTE Focus is shifted away from the Visual LISP Editor and to AutoCAD when you execute a 
function from the Console window that requires user input. 


Checking and Loading Code in the Current Editor Window 

The ability to check code and perform parentheses matching in code is an important feature 
that makes the Visual LISP Editor more efficient than Notepad. Once you are done checking the 
code in your programs, you can load all the code or just the code that is selected in the current 
editor window. 


CHECKING CODE 


The code-checking tool validates that the code in the current editor window will load success- 
fully into AutoCAD and even checks for too many or too few arguments being passed to the 
functions used in the code. However, the argument values being passed to a function aren't 
checked. You can use code checking in one of two ways: 


@ To check the code in the current editor window, click Check Edit Window on the Tools tool- 
bar or choose Tools > Check Text In Editor. 


@ Ifyou don’t want to check all of the code in the current editor, select the code you want to 
check and click Check Selection on the Tools toolbar or choose Tools > Check Selection. 


Checking stops when an error is encountered or when the file has been successfully checked. 
The Visual LISP Editor then displays the Build Output window. If an error was encountered 
during checking, an error message and the faulty code are displayed in highlighted text (see 
Figure 11.7). Double-clicking the highlighted text in the Build Output window causes Visual 
LISP to highlight the faulty code in the editor window as well. 
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MATCHING PARENTHESES 


Keeping parentheses balanced in AutoLISP programs is an ongoing challenge. The Visual 
LISP parentheses-matching tools can help you identify a missing parenthesis. You can either 
select code between two balanced parentheses or move the cursor between matching paren- 
theses. If you suspect you are missing a parenthesis, you can step through the code, match- 
ing parentheses to see if (and where) an opening or closing parenthesis is missing. When 

you select a Parentheses Match option, Forward moves the cursor toward the end of the file, 
whereas Backward moves the cursor toward the beginning of the file. If Parentheses Match or 
Parentheses Select cannot find the balancing parenthesis, Visual LISP sounds an audible bing. 
The cursor is not moved; no code is selected. 


D Real World Scenario 
PLAYGROUND DISASTER TO INCOMPLETE CODE 


To save time and typos, you are copying and pasting partial code statements from another program 
when you get a call from your child’s school. Your daughter fell off the monkey bars and needs 
stitches. You save your work, go pick up your child, rush off to the emergency room, soothe her 
while she’s being stitched up, take her home, and don’t get back to work until the next day. 


The fact that you pasted partial code statements and didn’t get to adding balancing parentheses 
(or removing the excess ones) before the call came in has completely slipped your mind. Out of 
habit, you open Visual LISP and, before adding any more code, you select the code block you added 
last and run Check Selection. Since the copy and paste left your program with three extra closing 
parentheses, an error message appears in the Build Output window. Starting at the end of the new 
code block, the Parentheses Match tools allow you to quickly step backward through the code, 
identify the partial code statements, and repair your code to working order. 


Here’s how you can use the Visual LISP parentheses-matching tools: 


To Find the Balancing Parenthesis for a Closing Parenthesis Click immediately before a 
closing parenthesis that you want to match. With the cursor positioned within the code in 
the current editor window, choose Edit > Parentheses Match > Match Backward. Visual LISP 
identifies the matching opening parenthesis. 


To Find the Balancing Parenthesis for an Opening Parenthesis Click immediately after an 
opening parenthesis that you want to match. With the cursor positioned within the code in 
the current editor window, choose Edit > Parentheses Match > Match Forward. Visual LISP 
identifies the matching closing parenthesis. 
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To View the Code between Matching Parentheses Click immediately after a closing 
parenthesis and then choose Edit > Parentheses Match > Select Backward. Or click imme- 
diately before an opening parenthesis and then choose Edit > Parentheses Match > Select 
Forward. Visual LISP selects the matching parentheses and the code between. 


TIP You can double-click in front of or after a parenthesis to have the Visual LISP Editor select 
the code between the adjacent parenthesis and the balancing parenthesis (the same as choosing 
Edit > Parentheses > Select Forward or Select Backward). 


LOADING CODE 


You can load the code in the current Visual LISP Editor window directly into AutoCAD. There is 
no need to use one of the methods for loading LSP files that I discussed in Chapter 10; you don’t 
need to copy and paste the code to the AutoCAD Command prompt. Click Load Active Edit 
Window on the Tools toolbar or choose Tools > Load Text In Editor to load all of the code in the 
current editor window. 

If you want to load only specific statements from the current editor window, select the code you 
want to load and click Load Selection on the Tools toolbar or choose Tools > Load Selection. After 
the code is loaded, switch to AutoCAD and use the loaded code. You can switch to AutoCAD from 
the Visual LISP Editor by clicking Activate AutoCAD on the View toolbar, by choosing Window > 
Activate AutoCAD, or by clicking the AutoCAD icon on the Windows taskbar. 


Debugging Code 

In addition to the formatting and checking tools that I have already covered in this chapter, the 
Visual LISP Editor supports a variety of debugging tools that can make locating and resolving 
problems easier within a program. The following explains several of the debugging tools that 
are available: 


Breakpoints Breakpoints allow you to interrupt the execution of a program that is loaded 
into the Visual LISP Editor and being executed in AutoCAD. When execution is inter- 
rupted, you can evaluate the values that have been assigned to variables and step through 
the remainder of the statements in the program to identify problems in real time. Position 
the cursor where you want to insert a breakpoint (typically immediately before an opening 
parenthesis), right-click, and choose Toggle Breakpoint from the context menu. The parenthe- 
sis is highlighted in red at the point where the program will be interrupted. After the break- 
point is set, execute the program in AutoCAD. Breakpoints set by the Visual LISP Editor 
work only while the program is open in the Visual LISP Editor window. 


Once execution is interrupted, you can use Step Into, Step Over, and Step Out on the Debug 
toolbar to step through a program statement by statement. 


@ Choose Step Into when you want to step through and evaluate all expressions of a 
code statement, even nested expressions. 


@ Use Step Over when you want to evaluate a code statement as a whole and are not 
interested in stepping through each nested expression one at a time. 


@ The Step Out tool resumes normal execution and ignores any further breakpoints that 
are set. 
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When you are finished, click Continue to resume normal execution until the next breakpoint 
is set, if one has been set, or click Reset to stop execution and abort the function that is cur- 
rently interrupted. Continue and Reset are also located on the Debug toolbar. The Step Into, 
Step Over, Step Out, Continue, and Reset (Quit) options can also be found on the Debug 
menu. 


Watch Window The Watch window allows you to see the current value assigned to a global 
or local variable while code is being executed from the Visual LISP Editor. You can see only 
the current value of a local variable when execution is paused by a breakpoint. You can add 
to the Watch window the variables or statements, known as watches, for which you want to 
see the current value by selecting and right-clicking the code in the editor window and then 
choosing Add Watch. A watch can be added before execution is started or while execution 

is paused by a breakpoint. If the Watch window isn’t displayed, click Watch Window on the 
View toolbar or choose View > Watch Window. 


Error Trace and Last Error Source Often when you are trying to debug a program, you 
aren't always sure where an error occurred. The Visual LISP Editor can help you identify the 
code that caused the error. Choose View > Error Trace to get information about the last error 
that occurred. In the Error Trace window, double-click each entry in the window to learn 
more about the error that occurred. Use the Last Error Source option on the Debug menu to 
select the code that caused the error. 


You will have a chance to use all three of these debugging features later in this chapter in the 


“Exercise: Working with the Visual LISP Editor” section. 
Table 11.1 lists some of the other debugging tools that the Visual LISP Editor offers. You can 
learn more about these debugging tools in the AutoCAD Help system. 


TABLE 11.1: Additional Visual LISP Editor debugging tools 


TOOL 


Break On Error 


Animate 


Inspect Window 


Trace Stack Window 


DESCRIPTION 


Suspends execution when an error occurs and allows you to evaluate variable val- 
ues and code statements to identify the origin of the error. Choose Debug > Break 
On Error to toggle the option. 


Slows the execution of a custom program so it can be watched in real time. Choose 
Debug > Animate to toggle the option. You can adjust the delay between state- 
ments by choosing Tools > Environment Options > General Options, clicking the 
Diagnostics tab, and specifying a new value in the Animation Delay text box. When 
the program is executed, the execution is similar to what happens if you manually 
click Step Into all the way through a program. 


Displays additional information about a symbol, value, or expression in a window. 


Traces the use of a function during the execution of a program. Trace Stack Window 
is a modernized version of the trace and untrace functions discussed in 
Chapter 9. 
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BROWSING THE OBJECTS IN A DRAWING 


The Visual LISP Editor also provides a few tools that allow you to step through and evaluate the 
graphical and nongraphical objects in a current drawing. Access these tools by choosing View > 
Browse Drawing Database and then selecting the option that lets you work with the objects you 
are interested in. 
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Creating a Visual LISP Project 


The Visual LISP Editor supports a concept known as projects. Projects are a means of grouping 
related program and data files. Projects are optional, but they can make opening and manag- 
ing multiple LSP and other resource files easy. You create a project by choosing Project > New 
Project and then specifying a location and name for the project in the New Project dialog box. 

In the Project Properties dialog box (see Figure 11.8), on the Project Files tab, you specify 
the files that you want to be part of the project and the order in which they should be loaded. 
Click the ellipsis button next to the Look In text box to specify the folder that contains the files 
you want to add to the project. Select a file from the list and click the > button to add the file to 
the project, or click the < button to remove a file from the project. Use the Top, Up, Down, and 
Bottom buttons to set the load order of the files in the project when compiled. 

The Build Options tab allows you to control compilation, merge files, and specify message 
modes along with the output locations for the project when it is compiled into an FAS file. 

An FAS file is a secure and faster-loading alternative to LSP files that doesn’t allow editing. 
AutoCAD will always try to load an FAS file in place of a LSP file, unless the LSP file is newer. A 
project can also be built into a standalone AutoCAD application known as a VLX file. 

A VLX file is secure, like an FAS file, but it can also be used to combine multiple program 
and resource files in a single file that can be loaded into AutoCAD. (You can learn more about 
creating VLX files in the next section.) I recommend leaving the settings alone since they are the 
best options for most programs, but feel free to experiment with them. You can learn more about 
these settings in the AutoCAD Help system. Click OK to create the new project (PRJ) file. Once 
you create a new project or open one (by choosing Project > Open Project), the project window 
opens (see Figure 11.9) with the name of the project displayed in the window’s title bar. 
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The project window allows you to do the following: 

Change the properties of a project 

Open a file by double-clicking it from the Files list in the main area of the project window 
Add files to a project 

Load and check the syntax of a file 

Load a selected LSP or FAS file 

Build FAS files for each LSP file in the current project 


+% ©% ©% >è >% ọọ% 


Close and save a project 


The toolbar displayed along the top of the project window gives you access to commonly 
used tools. Additional tools are available via context menus that open when you right-click a file 
or an empty area in the project window. 

Once you've added files to your project and specified the project’s settings, choose 
Project > Build Project FAS to compile the LSP files into FAS files—one FAS file for each LSP file 
by default. Then, review the output locations in the Build Output window to determine where 
the generated files were placed. The Visual LISP Editor places the FAS files in the same folder as 
the PRJ file unless you specified a different location in the Project Properties dialog box. Once an 
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FAS file has been built, you can load the file using the same methods described in Chapter 10 for 
loading a LSP file. 


Compiling LSP and PRJ Files into a VLX File 


You've seen that a LSP file can be compiled into an FAS file after it has been added to a PRJ 

file. You can also combine and compile LSP and PRJ files into a VLX file by using the New 
Application wizard. Unlike FAS files, VLX files can also contain the resource files that the LSP 
or FAS files require. Resource files can be TXT files (data sources) or DCL files, which are used to 
implement dialog boxes with an AutoLISP program. I cover creating dialog boxes for AutoLISP 
in Chapter 13, “Implementing Dialog Boxes (Windows only).” 


NOTE Check with your company’s IT department before compiling and distributing your LSP 
files and projects as VLX files. Some companies don’t allow VLX files on their network simply 
because of the associations they have with some computer viruses and the inability to see the 
code in the files. However, LSP and FAS files have also been known to be used to spread computer 
viruses. Use the security features Autodesk offers in the latest releases of AutoCAD, suchas the 
Trusted Locations option in the Options dialog box, to help prevent the loading and execution 
of malicious code. 


To generate a VLX file, choose File > New Application Wizard. The New Application wizard 
offers two modes: Simple and Expert. The following steps describe how to create a VLX file 
using the Expert mode: 


1. Start the New Application wizard in Expert mode. 


2. On the Application Directory page, specify a location and name for the application. Click 
Next. 


3. If you wish to protect your application’s namespace, select the Separate Namespace 
option on the Application Options page. If not, leave the option unchecked. Click Next. 


When you select the Separate Namespace option, the wizard will create a separate 
namespace for the functions and variables in your custom program. That way, when you 
load the VLX file they are not overwritten by AutoCAD-defined functions and variables 
that have the same name. 


4. On the LISP Files To Include page, select the LSP, FAS, or PRJ files that you want to add to 
the application and set the load order for the files. Click Next. 


5. If you have LSP, FAS, PRJ, DCL, or TXT files that you want to add as resources for the 
application, select them on the Resource Files To Include page. Resources are optional; 
you do not need to select any files. When you are finished, click Next. 


6. On the Application Compilation Options page, select Standard. Optionally, you can 
choose Optimize and Link, which might provide your program with better performance. 
When you are finished, click Next. 


7. On the Review Selections/Build Applications page, select the Build Application check 
box and click Finish. The wizard saves the application make (PRV) file and builds the 
VLX file. 
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You can use the other options under File > Make Application to load and rebuild a VLX file 
from an existing PRV file. The original files that were added to the PRV file must still be avail- 
able, though. Once you've built a VLX file, you can load it using the same methods described in 
Chapter 10 for loading a LSP file. 


Exercise: Working with the Visual LISP Editor 


In this section, you will take another look at the badcode function from Chapter 9 to demon- 
strate some of the AutoLISP functions for debugging a program. You will also have an oppor- 
tunity to continue to work with the drawplate function originally introduced in Chapter 2, 
“Understanding AutoLISP.” The key concepts I cover in this exercise are: 


Formatting, Checking, and Debugging Code The Visual LISP Editor provides many great 
features that assist you in formatting and checking code. The formatting and checking tools 
also provide a basic level of debugging tools to ensure the structure of your code is sound. 


Stepping Through and Inspecting Code Although the debugging techniques I described 
in Chapter 9 are essential, breakpoints—which allow you to interrupt and then step through 
your code—can be great time-saving tools. While a program is interrupted, the Visual LISP 
Editor also lets you inspect code and variable values in real time. 


Organizing LSP Files into a Project Projects make accessing your LSP files much easier 
compared to having to browse for and open each file that you want to access. Files added to 
a project can also be compiled to secure your custom programs from users who shouldn't be 
making changes to them. 


NOTE Thestepsin this exercise depend on the completion of the steps in the “Exercise: Handling 
Errors in the drawplate Function” section of Chapter 9. If you didn’t complete the steps, do so 
now or start with the ch11_drawplate. lsp and chli_utility.lsp sample files available 
for download from www. sybex.com/go/autocadcustomi zation. Place these sample files in 
the MyCustomF7 les folder within the Documents (or My Documents) folder or in the location 
you are using to store the LSP files. Once you've stored the sample files on your system, remove 
the characters ch11_ from each filename. 


Formatting, Checking, and Debugging the badcode Function 
Often when you start a new project, formatting code takes a backseat to the actual problem 
you are trying to solve. However, once you encounter a problem within your code, you will 
understand why accomplished programmers spend time formatting their code. Once the code 
is formatted, checking it is much easier since you can visually determine where a parenthesis or 
quotation mark is missing. 

The following steps explain how to format, check, and debug the badcode function for 
problems, and then fix those problems: 


1. At the AutoCAD Command prompt, type vlide and press Enter. 
2. Inthe Visual LISP Editor, choose File > Open File. 


3. When the Open File To Edit/View dialog box is displayed, browse to either the 
MyCustomFi les folder within the Documents (or My Documents) folder or the location 
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of the exercise files for this book. Select the ch11_debuggingex. lsp file and 
click Open. 


The code in the editor window should look like the code shown on the left side of 
Figure 11.10. By the end of this exercise, it will look like the code on the right—and you 
won't have had to format each line one at a time. 


FIGURE 11.10 
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4. Choose Tools > Format Code In Editor. An Info message box appears with the message 
Formatting stopped:Unbalanced token. This is the result of a missing closing paren- 
thesis. Click OK to close the message. 


The formatting tools available through the Visual LISP Editor work only with code that has 
valid structure and can be loaded into AutoCAD. Use the next steps to troubleshoot and repair 
the code so it can be properly formatted: 


1. With the chl1_debuggingex.1sp file open in the current editor window, choose Tools > 
Check Text In Editor. 


2. Inthe Build Output window, double-click the highlighted error message ; error: 
malformed string on input. 


You are returned to the badcode function editor window, but the text it highlights is not 
exactly near the problem since the Visual LISP Editor simply counts quotation marks to 
determine balance. Most of the text in the editor window is displayed in the color (magenta 
is the default) applied to the string data type as a result of a missing quotation mark. 


3. Find the code (getstring "\nEnter a string: ) and change it to (getstring "\ 
nEnter a string: "). 


Notice that the text color changes as a result of adding the missing quotation mark. 
4. Choose File > Save. 
In the next steps, you'll locate and add a missing parenthesis: 
1. Choose Tools > Check Text In Editor. 


2. Inthe Build Output window, double-click the highlighted error message ; error: 
malformed list on input. 


You are returned to the badcode function editor window, and now all of the text is high- 
lighted, indicating a closing parenthesis is missing. 
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3. Click after the last parenthesis of the badcode function and then choose Edit > 
Parentheses Matching > Select Forward. 


Notice the code is selected backward to the statement that starts with (if str instead of bal- 
ancing the defun function. The missing parenthesis is somewhere inside the highlighted text. 


4. Double-click to the right of the closing parenthesis that is located above the (princ) code 
statement. 


Notice the code is selected backward to the statement that starts with (progn instead of 
balancing the (if str statement. 


5. Double-click to the right of the closing parenthesis that is located above the one you 
clicked to the right of in step 4. 


The (if int (prompt (strcat "\nDivisor: " (rtos (/ 2.0 int)))) code 
statement and the closing parenthesis are selected. 


6. Double-click to the right of the (if int (prompt (strcat "\nDivisor: " (rtos 
(/ 2.0 int)))) code statement. 


Only part of the code statement is highlighted now: (prompt (strcat "\nDivisor: 
" (rtos (/ 2.0 int)))). 


7. Add a closing parenthesis at the end of the (if int (prompt (strcat "\nDivisor" 
(rtos (/ 2.0 int)))) statement to balance out the statement. 


8. Choose File > Save. 


In the next steps, you'll identify and address a problem related to passing too many argu- 
ments to a function: 


1. Choose Tools > Check Text In Editor. 


2. Inthe Build Output window, double-click the highlighted error message ; warning: 
too many arguments: (PROMPT "\nValue entered: " STR). 


You are returned to the badcode function editor window and the bad statement is now 
selected. 


3. Change (prompt "\nValue entered: " str) to (prompt (strcat "\nValue 
entered: " str)). 


4. Choose Tools > Check Text In Editor. 

No error is returned this time, so the code can now be formatted. 
5. Close the Build Output window and choose Tools > Format Code In Editor. 
6. Choose File > Save. 


The results you get should be similar to those shown on the right side of Figure 11.10. 


Stepping Through and Inspecting the badcode Function 

In this exercise, you'll continue to work with the chl1_debuggingex. lsp file that you checked, 
formatted, and performed some basic debugging on already in the previous section. Stepping 
through code line by line allows you to visually identify what is happening in your code, 


FIGURE 11.11 


Breakpoint set in (defun ¢:BadCode (/ str int) ; Prompt for string 
the editor window [lsetq str (getstring “\nEnter a string: “)) 
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whether it is executing as expected or if an error occurs, and see which branches of a program 
are being followed based on the results of the logical tests. Additionally, you can view the cur- 
rent values of the variables in the program at specific times to ensure they have the correct data 
before they are passed to a function. 


The following steps explain how to set a breakpoint, step through code, and view the current 


value of a variable: 


1. Open the Visual LISP Editor and the ch11_debuggingex. lsp file if they are not already open. 


2. In the editor window, locate and click immediately before the statement that starts with 
(setq str. 


3. Right-click and choose Toggle Breakpoint to add a breakpoint to the opening parenthesis 
of the statement. 


The opening parenthesis should change color and appear in a colored background (white 
text on a red background is the default); this indicates that a breakpoint has been set (see 
Figure 11.11). 


Ch21_DebuggingEx.lsp 


; If str is not nil, continue 
(if str 


4. Locate and add a breakpoint to the opening parenthesis of the statement that starts with 
(if int. 


5. Choose Tools > Load Text In Editor. 
6. Switch to AutoCAD. 
7. At the Command prompt, type badcode and press Enter. 


Execution of the function starts and the Visual LISP Editor is brought back to the foreground 
when execution is interrupted at the first breakpoint. You can tell execution has been inter- 
rupted because the line of code with the first breakpoint is selected, but also because the tools 
on the left side of the Debug toolbar are now enabled, as shown in Figure 11.12. 


i 
FIGURE 11.12 [EN Visual LISP for AutoCAD <Drawing1.dwg> - [Ch21_DebuggingEx.lsp] 
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8. Select the text str in the statement that starts with (setq str. Right-click and choose 
Add Watch. If the Add Watch dialog box is displayed, click OK. 


The Watch window is displayed and lists the str variable and its current value (see 
Figure 11.13). 
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FIGURE 11.13 Bi Watch = 
Watching variable eo ayy 
values with the - 

STR = nil 


Watch window 


NOTE You can remove variables from the Watch window. Select the variable in the Watch 
window that you wish to remove, right-click, and choose Remove From Watch. 


9. 


10. 


11. 
12. 


13. 
14. 
15. 


Select the text int in the statement that starts with (setq int and right-click. Choose 
Add Watch. If the Add Watch dialog box is displayed, click OK. 


On the Debug toolbar, click Step Into (or choose Debug > Step Into) twice. 


Evaluation of the statement is moved to the inner list, (getstring "\nEnter a string: "), 
and then the statement is evaluated. Focus shifts to AutoCAD; if it doesn't, you might not have 
clicked Step Into enough times. 


At the Enter a string: prompt, type debug and press Enter. 
The Visual LISP Editor becomes the focus. Click Step Into again. 


In the Watch window, the value of the str variable is now shown as debug instead of its 
previous value of nil. 


On the Debug toolbar, click Continue (or choose Debug > Continue). 
At the Enter an integer: prompt, type 0 and press Enter. 
On the Debug toolbar, click Step Over (or choose Debug > Step Over). 


As a result of trying to divide 2 by 0, an error occurred and the program stopped execut- 
ing. You can tell an error occurred because the text _1$ is displayed in the Visual LISP 
Console window. _1$ indicates that the program was left in debugging. The Reset button 
on the Debug toolbar is also still activated, another sign that debugging is still available 
and that the program didn’t end successfully. 


NOTE Remember that Step Over evaluates all nested statements as a whole and doesn't step you 


through each nested statement one at a time. You could have clicked Step Into in the previous 


step, but it would take using Step Into more than 10 times to get through the code. 


16. 


Choose View > Error Trace. 


When the Error Trace window opens, information about the most recent error that 
occurred in AutoLISP is displayed (see Figure 11.14). Typically, the first entry represents 
the error message; it is followed by the statement and function name where the error 
occurred. 
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FIGURE 11.14 m Error trace =) 
Viewing informa- aq 
tion about the 
<1> :/ERROR-BREAK 
recent error [2] (/ 2.0 0) 
[3] (C:BADCODE) 


<4> :CALLBACK-ENTRY 
<5> -ARQ-SUBR-CALLBACK 
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17. In the Error Trace window, double-click the first entry. A message box with the message 
:ERROR-BREAK: divide by zero is displayed. This is similar to the message you would 
see at the AutoCAD Command prompt. Click OK. 


TIP To resolve this problem, you should add an if statement to the code to ensure that the 
program never tries to divide by 0. Adding this code to the program is beyond the scope of this 
exercise. 


18. In the Error Trace window, right-click the second entry; (/ 2.0 0). Choose Call Point 
Source. 


The statement that caused the error is highlighted. 


19. Choose View > Breakpoints Window. When the Breakpoints window is displayed, click 
Delete All. All the breakpoints you set earlier are removed. 


20. Choose Window > Activate AutoCAD and execute the badcode function again. Enter the 
values debug and 2 this time. 


The function completes as expected and the output from the function is displayed in the 
command-line window. 


Creating and Compiling a Project 
Projects make it easy to access your LSP files or those that are related to a set of functions. 
Although creating a project is optional, doing so can save you some time managing complex 
programs by making everything available from a single place, especially since files need to be 
opened in the Visual LISP Editor to take advantage of the editor’s debugging tools. 

The following steps explain how to create a project for the drawplate function: 


1. At the AutoCAD Command prompt, type vlide and press Enter. 
2. Inthe Visual LISP Editor, choose Project > New Project. 


3. When the New Project dialog box is displayed, browse to either the MyCustomFiles 
folder within the Documents (or My Documents) folder or the location where you stored 
the exercise files for this book. 


4. In the File Name text box, type drawplate and click Save. 
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10. 
11. 


TIP 


When the Project Properties dialog box is displayed, click the ellipsis button to the right 
of the Look In text box. Browse to the folder you specified in step 3. 


Choose Drawplate and Utility from the Files list box (located on the left, below the Look 
In text box) and click >. 


Click OK. 


In the DrawPlate project window, double-click the DrawPlate item. Notice the file is 
opened in an editor window and is ready for you to make changes. 


In the editor window, change (load "utility.lsp") to (load "utility") so that 
AutoCAD loads the FAS or LSP file if either is found. You will remember that AutoCAD 
will always try to load an FAS file in place of a LSP file, unless the LSP file is newer. 


On the toolbar of the DrawPlate project window, click Build Project FAS. 


Switch to AutoCAD and create a new drawing. Load the drawplate. fas file with the 
app load command. 


The FAS file should be placed in the same folder as the project. If you cannot find the file, 


return to the Visual LISP Editor and review the path location of the FAS file in the Build Output 
window. 


12. 


At the Command prompt, type drawplate and press Enter. Follow the prompts that are 
displayed. The plate should be created as expected. 


FÀ 


Chapter 12 


Working with ActiveX/COM 
Libraries (Windows only) 


The AutoLISP® functions you have learned up to this point have been, for the most part, plat- 
form neutral and are unofficially known as Classic AutoLISP or Core AutoLISP. Starting with the 
Autodesk® AutoCAD® 2000 program, AutoLISP saw an architecture change that allowed for the 
use of the Microsoft ActiveX technology. ActiveX is a technology that enables applications to 
communicate and exchange information. COM (Component Object Model) is a library of objects 
that let you make changes to or query exposed objects. COM is an example of ActiveX. 

In this chapter, you will learn the basics of using ActiveX with AutoLISP and how to leverage 
the AutoCAD, Microsoft Windows, and Microsoft Office COM libraries. Although this chapter 
doesn’t go into great depth, it will give you a starting point and a general understanding of the 
functions you need to become familiar with in order to use ActiveX and access COM libraries. 
The primary reasons to use COM are to monitor actions in AutoCAD with reactors, access exter- 
nal applications such as Microsoft Word or Excel, and work with complex objects, such as tables 
and multileaders. 


Understanding the Basics of ActiveX 


ActiveX is the technology that allows for the use of COM. It is often associated with Visual Basic 
for Applications (VBA) and Visual Basic (VB) scripting these days, but it can be used by many 
modern programming languages, such as VB.NET and C++. Although many people refer to 
ActiveX and COM as the same thing, they aren’t. ActiveX is the technology that was developed 
by Microsoft to allow software developers to expose objects using COM, thereby letting pro- 
grammers communicate with the programs in new ways. 

In general, there are three concepts you need to understand about working with ActiveX in 
AutoLISP programs: 


@ Classes, objects, and collections 
@ Methods and properties 


@ Variant and array data types 
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Accessing Classes, Objects, and Collections 


Classes are the elements on which a COM library is built—think of them as a recipe. The 
AutoCAD COM library has classes for the AutoCAD application, a drawing (known as a docu- 
ment) file, and the graphical and nongraphical objects that are stored in a drawing. An object is 
an in-memory and unique instance of a class. Although a collection is also an object, it is a con- 
tainer for objects of the same type. 


WORKING WITH OBJECTS 


The vla-object data type is used in AutoLISP to represent an object or collection. (You'll learn 
how to work with the AutoCAD COM library in the “Using the AutoCAD COM Library” 
section, and with the COM libraries related to Windows and Microsoft Office in the “Leveraging 
the Windows and Microsoft Office COM Libraries” section, later in this chapter.) Many of the 
objects you will want to work with can be accessed using properties and methods described 

in the next section. However, there are some objects that you must create or get an instance of 
before you can work with them. 

For example, you can use the vlax-create-object function to create an instance of an appli- 
cation or secondary object that isn’t accessible from an object that is already in memory. The 
vlax-get-object function can be used to get an instance of an object that is already in memory. 
When an object is in memory, it can be accessed and manipulated. The following shows the 
syntax of the vlax-create-object and vlax-get-object functions: 


(vlax-create-object prog_id) 
(vlax-get-object prog_id) 


The prog_id argument is a string that represents the program ID of the object you want to 
create or get. The program ID follows the syntax of vendor.component, and it can optionally 
have a version number as well, for a syntax of vendor.component.version. Typically, vendor 
is the name of the software or company that created the component, whereas component is 
commonly a class. 

For example, if you wanted to create or check for an instance of AutoCAD you would use the 
program ID of AutoCAD.Application. The AutoCAD program ID optionally supports a version 
number that allows you to look for a specific AutoCAD release. The version number always con- 
sists of a major value, while some version numbers can contain both a major and a minor value. 
The major version of 19 is shared between AutoCAD 2013 and 2014, but if you want to refer to 
AutoCAD 2014 you use the minor number of 1. The program ID for AutoCAD 2014 is AutoCAD 
-Application.19.1. If you want to reference AutoCAD 2015, you use AutoCAD. Application. 20 
for the program ID. Refer to the AutoCAD Help system for the version number assigned to your 
AutoCAD installation. 

The vlax-create-object and vlax-get-object functions return a vla-object if a new 
object is created or if an object with the program ID is already in memory; nil is returned if the 
object couldn't be created or retrieved from memory. The following shows how to create a new 
instance of the AutoCAD True Color (AcCmColor) and Microsoft Word (Application) objects. 
The AcCmColor object is used to manipulate the color value assigned to a drawing object. 


; Creates an instance of an AutoCAD True Color object 
(setq clrObj (vlax-create-object 
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(strcat "AutoCAD.AcCmColor." 
(substr (getvar "acadver") 1 2)))) 
#<VLA-OBJECT IAcadAcCmColor 000000002dcdd650> 


; Creates an instance of the most recently used Microsoft Word application 
(setq wordObj (vlax-create-object "Word.Application") ) 
#<VLA-OBJECT _Application 000000002f1e3c78> 


; Attempts to create an instance of the Microsoft Word 2010 application 
; but the application is not installed on this workstation 

(setq wordObj (vlax-create-object "Word.Application.14") ) 

nil 


; Creates an instance of the Microsoft Word 2013 application; installed 
(setq wordObj (vlax-create-object "Word.Application.15")) 
#<VLA-OBJECT _Application 000000002f1e3b98> 


The following shows how to get an instance of the Microsoft Word application that has 
already been started: 


; Gets an instance of a non-version-specific release of the 
; Microsoft Word application that is in memory 


(setq wordObj (vlax-get-object "Word.Application") ) 
#<VLA-OBJECT _Application 000000000a92e568> 


Although you can use the vlax-get-object function to get an instance of an object in mem- 
ory, or create a new instance of an object with the vlax-create-object function, the vlax- 
get-or-create-object function combines the functionality of both. If an object already exists, 
vlax-get-or-create-object returns the object and, if not, a new instance of the object is cre- 
ated. vlax-get-or-create-object has the same syntax as vlax-create-object. 


3; Gets/creates an instance of the most recently used Microsoft Word application 
(setq wordObj (vlax-get-or-create-object "Word.Application") ) 
#<VLA-OBJECT _Application 000000000a92e568> 


When an object is created with the vlax-create-object or vlax-get-or-create-object 
function, it must be released from memory when it is no longer used. You use the vlax-release- 
object function to release an object; the function must be passed the value returned by the 
vlax-create-object or vlax-get-or-create-object function. The vlax-release-object 
function returns a random integer value that has no specific meaning if the value it was passed is 
a valid object; an error is returned if the value passed wasn’t a valid object that could be released. 

The following code shows how to release an object created with the vlax-create-object or 
vlax-get-or-create-object function: 


(vlax-release-object wordObj) 

(0) 

(vlax-release-object cObj) 

; error: null interface pointer: #<VLA-OBJECT 0000000000000000> 
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WORKING WITH COLLECTIONS 


Collections are objects that can be queried and modified using properties and methods, but 
they are also containers that hold similar objects. A collection fundamentally is similar to a 
symbol table; you can work with a symbol table and add new objects to it, but you can’t create 
a new symbol table. All the collections that you need in order to work with AutoCAD objects 
are defined as part of the AutoCAD ActiveX API. For example, a Layers collection contains all 
of the Layer objects in a drawing, and a Documents collection contains all the open drawings 
(or Document objects) in the current AutoCAD session. You can get an object from a collection 
using the Item method, add a new object to a collection using the Add method, and remove an 
object from a collection using the Delete method. 

If you want to step through a collection and perform a set of statements on each object, you 
can use the vlax-for AutoLISP function, which is similar to the foreach function. The follow- 
ing shows the syntax of the vlax- for function: 


(vlax-for var coll [expressionN ...]) 


Here are its arguments: 


var The var argument specifies the user-defined variable, which you use to reference the 
current item of the coll argument as the collection is being stepped through. 


coll The coll argument specifies a collection object of the vla-object data type, which 
should be stepped through one item at a time. 


expressionN The expressionN argument represents the expressions that should be exe- 
cuted when each object in the coll argument is found. The object is located using the name 
in the var argument. 


The following is an example of the vlax- for function that steps through the Layouts collec- 
tion and returns the name of each layout in a drawing: 


; Imports the functions for the AutoCAD COM library, 
3 if not already available 
(vl-load-com) 


; Gets the current drawing 
(setq curDoc (vla-get-activedocument (vlax-get-acad-object))) 


; Gets the Layouts collection 
(setq layouts (vla-get-layouts curDoc)) 


; Creates a report header 
(prompt (strcat "\nLayouts count: " (itoa (vla-get-count layouts) ))) 
(prompt "\nLayouts: ") 


; Steps through the objects in the collection 


(vlax-for layout layouts 
(prompt (strcat "\n " (vla-get-name Layout) )) 


; The output from the previous expressions 
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Layouts count: 3 
Layouts: 
Layoutl 
Layout2 
Model 


You can use the vlax-map-collection function to execute a single AutoLISP function 
on each object in a collection. The following shows the syntax of the vlax-map-collection 
function: 


(vlax-map-collection coll 'func) 
Here are its arguments: 


coll The coll argument specifies the collection object, of the vla-object data type, that 
should be stepped through one item at a time. 


‘func The func argument represents the function you want to execute on each object in the 
coll argument. An apostrophe must be placed in front of the function name to let AutoLISP 
know it is a value that should not be evaluated. 


Specifying Properties and Invoking Methods 

A class uses two different approaches to expose itself to a programming language such as 
AutoLISP or VBA: properties and methods. They are available when an instance of a class is 
created in memory as an object. Properties are used to describe and query the characteristics 
of an object. For example, the Length and TrueColor properties of a Line object are used to 
specify that line’s length and color. Properties can be designated as read-only. 

Methods are used to manipulate and perform an action on an object. ActiveX allows you 
to define two types of methods: subroutines and functions. Subroutines never return a value; 
functions can return a single value. For example, the Delete and Copy methods are used 
to remove or duplicate an object in a drawing. The Delete method doesn’t return a value, 
whereas the Copy method returns a new instance of an object. 

The objects in a COM library are typically unique, so the vLax-dump-object function can be 
used to list the properties and methods that a particular object supports. The following shows 
the syntax of the vLax-dump-object function: 


(vlax-dump-object obj [flag]) 
Here are its arguments: 


obj The obj argument is a value of the vla-object type, which is returned by a method or 
property, or is available as the var argument of the vlax- for function. 


flag The flag argument is an optional argument that allows you to specify whether the 
returned output lists only the properties or the properties and methods supported by an 
object. A value of T returns both supported properties and methods, whereas no value or a 
value of nil returns only the supported properties. 


Here’s an example that shows how to list the properties and methods of an object with the 
vlax-dump-object function: 


(setq clrObj (vlax-create-object 
(strcat "AutoCAD.AcCmColor." 
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(substr (getvar "acadver") 1 2)))) 
#<VLA-OBJECT IAcadAcCmColor 000000002dcdd650> 


(vlax-dump-object clrObj T) 

; IAcadAcCmColor: AutoCAD AcCmColor Interface 
; Property values: 

; Blue (RO) = 0 

: BookName (RO) = "" 

; ColorIndex = 0 

; ColorMethod = 195 

; ColorName (RO) = "" 

4 EntityColor = -1023410176 

; Green (RO) = 0 


4 Red (RO) = 0 
; Methods supported: 
: Delete () 


; SetColorBookColor (2) 
; SetNames (2) 
; SetRGB (3) 


(RO) after a property name indicates that the property is read-only and the value cannot be 
changed. The number in the parentheses after each method listed in the Methods supported 
section of the output indicates the number of arguments that the method expects; no number in 
the parentheses indicates the method doesn’t accept any argument values. 


GETTING AND SPECIFYING THE VALUE OF AN OBJECT’S PROPERTY 


The vlax-get-property and vlax-put-property functions are used to query and set the values 
of an object property. The vlax-get-property function returns the current value of the object 
property; the vlax-put-property function returns nil if the value was successfully assigned 
to the object’s property. When the value of a property is changed with the vlax-put-property 
function, the object is updated immediately. Refer to the COM library’s documentation for the 
type of value that will be returned or that the property expects. See the section “Using the 
AutoCAD COM Library” to learn how to access information on the AutoCAD COM library help. 
The following shows the syntax of the vlax-get-property and vlax-put-property functions: 


(vlax-get-property obj 'prop) 
(vlax-put-property obj 'prop val) 
Here are their arguments: 


obj The obj argument is a value of the vla-object type, which is returned by a method or 
property, or is available as the var argument of the vlax- for function. 


‘prop The prop argument specifies the name of the particular property you want to query 
or set. The property name must be prefixed with an apostrophe. An apostrophe must be 
placed in front of the property name to let AutoLISP know it is a value that should not be 
evaluated. 


val The val argument specifies the new value to be assigned to the property. 
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Here are some examples that show how to get and set a property value of an object. In these 
examples, you work with the ColorMethod and ColorIndex properties of an AutoCAD True 
Color object: 


(setq clrObj (vlax-create-object 
(strcat "AutoCAD.AcCmColor." 
(substr (getvar "acadver") 1 2)))) 


; Sets the value of the ColorMethod property to acColorMethodByACI 
3; acColorMethodByACI indicates that the color should 

; be based on an ACI color value 

(vlax-put-property clrObj 'ColorMethod acColorMethodByACTI) 

nil 


; Gets the current value of the ColorIndex property 

; A value of 256 specifies that the color represents ByLayer 
(vlax-get-property clrObj 'ColorIndex) 

256 


; Releases the AutoCAD True Color object because it was created with 
; the vlax-create-object 
(vlax-release-object clr0bj) 


In the previous example, acColorMethodByACI is a constant variable value that is exposed as 
part of the AutoCAD COM library. This constant value tells AutoCAD you want to work with 
one of the standard 255 ACI colors, and not a True or Color Book color. 

You can determine whether an object supports a specific property by using the vlax- 
property-available-p function. A value of T is returned if the object supports the specified 
property. The following shows the syntax of the vlax-property-avai lable-p function. See the 
argument descriptions of the vlax-get-property function earlier in this section: 


(vlax-property-available-p obj 'prop) 


INVOKING AN OBJECT METHOD 


The vlax-invoke-method function is used to execute an object method and pass to that method 
any argument values that are expected. A value can be returned by the method through the 
executed vlax-invoke-method function or by reference to the variables passed to the method. 
Refer to the particular method’s documentation for the type of values that can be passed or for 
an explanation of the values returned by the method. (See the section “Using the AutoCAD 
COM Library” later in this chapter to learn how to access information on the AutoCAD COM 
library help.) 

The following shows the syntax of the vLax-invoke-method function: 


(vlax-invoke-method obj 'method [argN ...]) 
Here are its arguments: 


obj The obj argument is a value of the vla-object type, which is returned by a method or 
property or is available as the var argument of the vlax- for function. 
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‘method The method argument is the name of the method you want to execute. The method 
name must be prefixed with an apostrophe. An apostrophe must be placed in front of the 
method name to let AutoLISP know it is a value that should not be evaluated. 


argN The argN argument is the value(s) to be passed to the method. If the argument you 
specify is meant to return a value, that argument must be prefixed with an apostrophe. The 
documentation in the AutoCAD Help system for the method will let you know if a value is 
passed back to the variable specified as an argument instead of returned by the function. For 
example, the GetBoundingBox method returns values to its two arguments that represent 
the minimum and maximum extents of an object. The code statement would look similar to 
(vlax-invoke-method lineObj 'GetBoundingBox 'min 'max). See the AutoCAD COM 
library documentation for additional information. 


Here is an example that shows how to invoke a method. This example sets the Red element 
of the RGB color to a value of 255 and the Blue and Green elements of the object to 0. The result 
would be a pure color of red if the color object was assigned to an object. The Red, Green, and 
Blue properties of an AutoCAD True Color object are read-only; the SetRGB method is used to 
assign new values to the three color elements of the object: 


(setq clrObj (vlax-create-object 
(strcat "AutoCAD.AcCmColor." (substr (getvar "acadver") 1 2)))) 
(vlax-invoke-method clrObj 'SetRGB 255 © 0) 
nil 
(vlax-release-object clr0bj) 


You can determine whether an object supports a method by using the vLax-method- 
applicable-p function. A value of T is returned if the object does support the specified method. 
The following shows the syntax of the vLax-method-applicable-p function. The arguments 
are the same as described earlier in this section: 


(vlax-method-applicable-p obj 'method) 


Working with Variants and Arrays 


vla-object isn’t the only new data type that you will have to understand when working with 
ActiveX. Many methods and properties use what is known as a variant. The variant data type 
is the chameleon of data types; it can represent any supported data type. A variant in AutoLISP 
is represented by the vla-variant data type. Arrays are yet another type of data that you will 
need to become familiar with. An array is represented by the vla-array data type and is 
similar to the AutoLISP list data type. 


MAKING VARIANTS 


Most properties and methods return or expect values of a specific type, but there will be times 
when you will need to assign a property or pass a method a variant value. Some data structures 
can represent multiple values, such as a point or Xdata, and in these situations the AutoCAD 
COM library is designed to return or accept a variant value. You define a variant by using the 
vlax-make-variant function. 

The following shows the syntax of the vLax-make-variant function: 


(vlax-make-variant [val [type] ]) 
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Here are its arguments: 
val The val argument is the value to be assigned to the variant and is optional. 


type The type argument is an optional integer that specifies the data type that the value 
should represent. As an alternative, you can use a constant variable value that has the same 
meaning. Table 12.1 lists some of the most common data types and the integer and constant 
variable values you can use. Refer to the vLax-make-variant topic in the AutoCAD Help 
system for more supported values. 


TABLE 12.1: Common data types used with the vlLax-make-variant function 


DATA TYPE INTEGER VALUE CONSTANT VARIABLE VALUE 
Integer 2 vlax-vbInteger 

Double 5 vlax-vbDouble 

String 8 vlax-vbString 


Here is an example that shows how to make a variant that holds an integer value of 5: 


(setq var (vlax-make-variant 5 vlax-vbInteger) ) 
#<variant 2 5> 


When neither the val nor the type argument is provided to the vlax-make-variant func- 
tion, an empty variant is returned. The value and type of a variant can be returned using the 
vlax-variant-value and vlax-variant-type functions. The value assigned to a variant can’t 
be changed, but the data type a variant represents can be changed using the vlax-variant- 
change-type function, making it possible to change an integer to a double or string. For exam- 
ple, you might want to change an integer or double value to a string so that it can be displayed 
to the user as part of a message or prompt string. 

The following shows the syntax of the vlax-variant-value, vlax-variant-type, and 
vlax-variant-change-type functions: 


(vlax-variant-value variant) 
(vlax-variant-type variant) 
(vlax-variant-change-type variant type) 


DEFINING ARRAYS 


The array data type is similar to the AutoLISP list data type, but typically an array is made up of 
a specified number of elements. You will remember that a list can hold any number of elements. 
A common use for arrays with the AutoCAD COM library is to represent a point list. Arrays can 
also be used to pass multiple objects to a method or for times when you want to return more 
than one value from a custom function. 

The vlax-make-safearray function is used to create a new array based on a specific data 
type and number of elements. The following shows the syntax of the vLax-make-safearray 
function: 
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(vlax-make-safearray type '(lbound . ubound) ['(lbound . ubound) ]) 
Here are its arguments: 


type The type argument is an integer or equivalent constant variable that represents the 
data type of the elements within the array. These are the same data types that the vlax- 
make-variant function supports. Refer to the vlax-make-safearray topic in the AutoCAD 
Help system for supported values. 


'(lbound . ubound) The lbound part of the argument is an integer that represents the 
lower element of the array, typically 0. The ubound part of the argument is an integer that 
represents the upper element of the array. If you want to specify an array of three elements, 
set Lbound to 0 and ubound to 2. 


NOTE The optional ['(lbound . ubound) ] argument allows you to define a matrix. For 
information on matrices, see the vlax-tmatrix function in the AutoCAD Help system and 
the Trans formBy method in the AutoCAD COM library. 


Here are examples that define arrays: 


; Array of three strings 
(setq arStrs (vlax-make-safearray vlax-vbString '(0 . 2))) 
#<safearray...> 


; 2D point (array of two doubles) 
(setq pt2D (vlax-make-safearray vlax-vbDouble '(@ . 1))) 
#<safearray...> 


After an array has been defined, you can add values to the elements within the array by 
using the vlax-safearray-put-element function. You can retrieve values within an array by 
using the vlax-safearray-get-element function. 

The following shows the syntax of the vLax-safearray-put-element and vlax-safearray- 
get-element functions: 


(vlax-safearray-put-element array idx val) 
(vlax-safearray-get-element array idx) 


Here are its arguments: 


array The array argument is a value of the vla-array data type, such as that returned by 
the vLax-make-safearray function. 


idx The idx argument is an integer that represents an element within the array. The value 
cannot be less than the lower or greater than the upper element of the array. 


val The val argument is the value that is to be assigned to the element in the array. 


Here are examples that assign values to and get values from the arrays defined in the earlier 
examples: 


; Assign strings to a three-element array 
(vlax-safearray-put-element arStrs 0 "Qty") 
"Qty" 


(vlax-safearray-put-element 
"Model" 
(vlax-safearray-put-element 
"Description" 


; Assign double/real values 
(vlax-safearray-put-element 
0.0 
(vlax-safearray-put-element 
5:25) 
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arStrs 1 "Model") 
arStrs 2 "Description") 
to a two-element array 
pt2D © 0.0) 


pt2D 1 5.25) 


; Get the first element in an array 


(vlax-safearray-get-element 
0.0 


pt2D 0) 


To create a 2D or 3D point array, you can use the vlax-3d-point function. Or you can assign 
multiple values to an array based on the values of a list with the vlax-safearray- fill func- 
tion. Here are examples that use the vlax-3d-point and vlax-safearray-fill functions: 


; 2D point 


(setq pt2D (vlax-3d-point 0. 


3; 3D point 


(setq pt3D (vlax-3d-point 0. 


0 5.25)) 


© 5.25 1.0)) 


; Adds three strings to a three-element array 


(vlax-safearray-fill arStrs 


'("Qty" "Model" "Description") ) 


Table 12.2 lists some additional functions that can be helpful when working with arrays. For 
more information on the functions mentioned in the table, see the AutoCAD Help system. 


DESCRIPTION 


TABLE 12.2: Additional array functions 
FUNCTION 
vlax-safearray-type 


< 


< 


Vv 


Vv 


lax-safearray-get-dim 


lax-safearray-get-1l-bound 


lax-safearray-get-u-bound 


lax-safearray->list 


Returns an integer that represents the data type of the values 
contained in an array 


Returns an integer that represents the number of elements in an 
array 


Returns an integer that represents the index of the lower element 
in an array 


Returns an integer that represents the index of the upper element 
in an array 


Returns a list containing the values of all elements in an array 
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Importing COM Libraries 


Although you can access the properties and methods of an object using the functions covered in 
the “Specifying Properties and Invoking Methods” section, importing a COM library can make 
coding easier. When you import a COM library, that library defines an AutoLISP function for 
the properties and methods of each class in the library. The newly defined functions that result 
from importing a COM library reduce the amount of code that needs to be written. 

For example, the vla-get-red function can be used instead of the vlax-get-property func- 
tion to get the current value of the Red property of an AutoCAD True Color object. The same is true 
with methods; vla-delete is the equivalent of using the vLax-invoke-method function with the 
Delete method name as an argument. The following two code statements produce the same result: 


(vlax-get-property clrObj 'Red) 
(vla-get-red clr0Obj) 


The properties and methods exposed by the AutoCAD COM library can be imported into a 
current drawing with the vl- load-com function. However, if you want to import the functions 
of another COM library for use with AutoLISP you must use the vlax-import-type-library 
function. The vlax-import-type-library function returns T if the COM library was success- 
fully imported. An error is returned if the COM library couldn’t be imported. 

The following shows the syntax of the vlax-import-type-library function: 


(vlax-import-type-library :tlb-filename filename 
[:methods-prefix me_prefix 
:properties-prefix prop_prefix 
:constants-prefix con_prefix] 


) 


Here are its arguments: 


filename The filename argument represents the path to and the filename of the COM 
library to be imported. 


me_prefix, prop_prefix, and con_prefix These arguments are optional strings that rep- 
resent the prefix to be appended to the property, method, and constant names in the COM 
library being imported to ensure the names are unique from other imported libraries. 


Here is an example that shows how to import the COM library for the Windows Shell object: 
(vlax-import-type-library :tlb-filename "c:\\windows\\system32\\wshom.ocx" 


:methods-prefix "wshm-" 
:properties-prefix "wshp-" 
:constants-prefix "wshk-" 


) 


Although you can import a COM library more than once, you should avoid doing so, since 
multiple imports can add to the time it takes for a custom function to execute. The following 
example shows how you can use a global variable to determine whether the COM library associ- 
ated with the Windows Shell object has already been imported into the current session: 


; Imports the Windows Host Scripting Library 
(if (= wshLibImported nil) 
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(progn 
(vlax-import-type-library :tlb-filename "c:\\windows\\system32\\wshom.ocx" 
:methods-prefix "wshm-" 
:properties-prefix "wshp-" 
:constants-prefix "wshk-" 
) 
(setq wshLibImported T) 
) 
(princ) 


) 


Using the AutoCAD COM Library 


Once the AutoCAD COM library has been imported, you can use the newly exposed 
functions to do the following: 


@ Access the objects associated with the AutoCAD application and current drawing 
@ Get the graphical and nongraphical objects stored in the current drawing 
@ Perform geometric calculations 


@ Register reactors and monitor changes made to a drawing or actions performed by the user 


TIP Before you use the AutoCAD COM library, make sure that you execute the vl- Load-com 
function to ensure the library has been imported. 


The classes in the AutoCAD COM library are organized using a hierarchy. The AutoCAD 
application is at the top, followed by the drawings (or documents) opened, and then the 
objects in a drawing. Once you have a drawing object, you can then access the nongraphical 
objects stored in the drawing. Graphical objects that have been placed in model space or 
on a layout are accessed through the special named blocks *ModelSpace and *PaperSpaced 
of, which are stored in the Blocks or Layouts collection. A drawing can contain more than 
one *PaperSpace block; each successive paper space block name in the drawing is incre- 
mented by 1. 


NOTE You can access the AutoCAD application object from most objects in the AutoCAD 
COM library by using the Application property, which can be accessed with the vla-get- 
application function. 


You can learn about the classes in the AutoCAD COM library by using the AutoCAD Object 
Model in the AutoCAD Help system. The AutoCAD Object Model can be found by going to 
http: //help.autodesk.com/view/ACD/2015/ENU/files/homepage_dev.htm and clicking the 
AutoCAD Object Model link. The AutoCAD Object Model (see Figure 12.1) shows the hierarchy 
of the AutoCAD COM library structure. 

When you click the object model, the reference topic for the associated class/object opens. 
The Help reference page provides information on how an object can be created, along with the 
properties and methods supported by the object. The content is intended primarily for the VBA 
programmer, but it is still very useful if you're working with the AutoCAD COM library in 
AutoLISP. 
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FIGURE 12.1 Object Model (Activex) 
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For the most part, adding vla- as a prefix for a method name or vla-put- or vla-get- as 
a prefix for a property name is all that is needed to convert the information contained in the 
VBA documentation for use with AutoLISP. (Remember that you must use vl- load-com to 
ensure that the AutoCAD COM library has been imported before you can use it.) A majority of 
the reference topics for object properties and methods also contain example code for use with 
AutoLISP. You can copy and modify the example code as needed. The ActiveX Developer’s 
Guide can also help you learn more about the AutoCAD COM library. 

You can access both the ActiveX Reference and ActiveX Developer's topics by using the 
AutoCAD Object Library Reference and Developer’s Guide links in the ActiveX/VBA section of 
the Developer homepage in the AutoCAD Help system. 


TIP When youare using the Visual LISP® Editor, you can highlight the name of an imported func- 
tion in the editor window and press Ctrl+F1 to open the related topic in the ActiveX Reference. 
Using this approach, you open the acadauto.chm file to the topic that discusses the object, 
method, or property. 


Accessing the AutoCAD Application and Current Drawing Objects 

Once the AutoCAD COM library has been imported with the vl- lLoad-com function, you can 
use the vlax-get-acad-object function to get the AcadApplication object that represents the 
AutoCAD application. As I mentioned earlier, the AutoCAD application object is the topmost 
object in the hierarchy that is the AutoCAD COM library. To learn which methods and proper- 
ties an AcadApplication object supports, you can use the vlax-dump-object function with the 
value returned by the vlax-get-acad-object function. Here is an example that shows how to 
use the vlax-get-acad-object function: 


3 Gets the AutoCAD application object 
(setq acad (vlax-get-acad-object) ) 
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The AcadApplication object contains a property named ActiveDocument, which returns an 
AcadDocument object that represents the current drawing. Use the vla-get-activedocument 
function to get the current drawing object. Here is an example: 


; Gets the current drawing 
(setq curDoc (vla-get-activedocument acad) ) 


Working with Graphical and Nongraphical Objects in the Current 
Drawing 

The graphical and nongraphical objects stored in a drawing can be accessed using ActiveX. As 
defined by the drawing architecture, all graphical objects are stored in a Block object and can 
be accessed from the Blocks collection. Model space and paper space are special types of Block 
objects that you can manipulate without performing any special operation. The Blocks collec- 
tion is just one of several collections that allow you to create and access nongraphical objects in 
a drawing. 


NOTE = The vla-object data type isn’t compatible with the ename data type. You can convert 
vla-object values to an entity name (ename) by using the vlLax-vla-object->ename func- 
tion. The vLax-ename->vla-object function converts an ename toa vla-object data type. 
Additionally, you can use the vla-get-handle function to get an object’s handle and then use 
the handent function to get an object’s ename based on a valid handle. These functions are 
helpful if you are mixing the use of Classic AutoLISP functions that work with the ename data 
type, such as entget or ssname, and those used to work with objects of the AutoCAD COM 
library. Examples of these functions, with the exception of vLax-vla-object->ename, can 
be found in the chl12_mswin_of fice. lsp file, which you can download from this book’s web 
page, www. sybex.com/go/autocadcustomization. 


In the previous section, you learned how to get the object that represents the active docu- 
ment. The next example shows how to get the ModelSpace or PaperSpace object based on the 
active space. You can determine the correct active space by using the ActiveSpace property of 
the current document. 


; Get a reference to the current space in AutoCAD 
(if (= (vla-get-activespace curDoc) acModelSpace) 
(setq space (vla-get-modelspace curDoc)) 
(setq space (vla-get-paperspace curDoc)) 


) 


When you want to add an object, such as a Layer object, to a collection, you can use one of 
the many Add methods available through the AutoCAD COM library. The following exercise 
shows how to create a function that checks for the existence of a layer and that creates the 
layer if it’s not found; it then sets the layer as current by using the AutoCAD COM library and 
ActiveX. The function is similar to the createlayer function that you defined in the utility 
. Lsp file in the various exercises throughout this book. 


1. Create a LSP file named ActiveX. lsp in the MyCustomFolders folder within the 
Documents (or My Documents) folder, or in the location you are using to store the LSP 
files. 
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2. In Notepad (Windows) or TextEdit (Mac OS), type the following in the text editor area: 


; Creates a new layer and/or sets a layer current 
(defun CreateLayer-ActiveX (lyrName layColor docObj / layerObj) 


(if (= (vl-catch-all-error-p 
(vl-catch-all-apply 
'vla-item 
'((vla-get-layers docObj) "Hatch")) 


) 
T 

) 
(progn 


; Creates the layer 
(setq layerObj (vla-add (vla-get-layers docObj) lyrName)) 


; Sets the color of the layer 
(vla-put-color layerObj layColor) 


; Sets the layer current 
(vla-put-activelayer docObj 
(vla-item (vla-get-layers docObj) lyrName) ) 


(princ) 


) 
3. Save the file and then load it into AutoCAD. 
4. At the Command prompt, type the following to test the function: 


(setq acad (vlax-get-acad-object) ) 
(setq curDoc (vla-get-activedocument acad) ) 
(createlayer-activex "NewLayer" 4 curDoc) 


A new layer named NewLayer is added to the drawing, assigned the color 4 (Cyan), and 
set as current. You can see that the new layer has been created by using the layer 
command and the Layer Properties Manager. 


Adding graphical objects to a drawing with ActiveX is different from what you have done 
previously when using the command, entmake, and entmakex functions. When using ActiveX, 
you must specify where an object should be created—the methods of the AutoCAD COM library 
are not contextually driven. You must explicitly work in model space or paper space. 

The following exercise defines a function that prompts the user for two points: the opposite 
corners of a rectangle. User input is handled using the methods available through the Utility 
object. The two points specified are used to define the four corners of a rectangle, by making an 
array of eight elements and then populating the XY pairs of each point defined for the rectangle. 
The array is used to specify the vertices of the lightweight polyline to add in the model space 
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of the current drawing. Once the lightweight polyline is added, the Closed property is used to 
close the lightweight polyline. 


1. 
2. 


Open the Activex. lsp file in Notepad (Windows) or TextEdit (Mac OS). 


Click after the last closing parenthesis of the createlayer-activex function and press 
Enter twice. 


In the text editor area, type the following: 


; Creates a rectangle on the Obj layer 
(defun c:DrawRectangle_ActivexX ( / docObj curLayer vPt1 vPt2 
ptList lwPlineObj) 
; Gets a reference to the current drawing 
(setq docObj (vla-get-activedocument (vlax-get-acad-object) ) ) 


; Gets the active layer 
(setq curLayer (vla-get-activelayer docObj)) 


; Creates and/or sets the Obj layer current 
(CreateLayer-Activex "Obj" acGreen docObj) 


; Prompts the user for a point 
(setq vPtl (vla-getpoint (vla-get-utility docObj) nil 
"\nSpecify first corner: ")) 


; Prompts the user for the opposite corner 
(setq vPt2 (vla-getcorner (vla-get-utility docObj) vPt1 
"\nSpecify opposite corner: ")) 


; Creates an array of four 2D points 

(setq ptList (vlax-make-safearray vlax-vbDouble '(0 . 7))) 

(vlax-safearray-fill ptList 

(list 

; Point 1 
(vlax-safearray-get-element (vlax-variant-value vpt1) 0) 
(vlax-safearray-get-element (vlax-variant-value vpt1) 1) 
; Point 2 
(vlax-safearray-get-element (vlax-variant-value vpt1) 0) 
(vlax-safearray-get-element (vlax-variant-value vpt2) 1) 
; Point 3 
(vlax-safearray-get-element (vlax-variant-value vpt2) 0) 
(vlax-safearray-get-element (vlax-variant-value vpt2) 1) 
; Point 4 
(vlax-safearray-get-element (vlax-variant-value vpt2) 0) 
(vlax-safearray-get-element (vlax-variant-value vpt1) 1) 
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; Gets a reference to the current space in AutoCAD 
(if (= (vla-get-activespace docObj) acModelSpace) 
(setq space (vla-get-modelspace doc0bj) ) 
(setq space (vla-get-paperspace docObj)) 
) 


; Draws the rectangle using a lightweight polyline 
(setq lwPlineObj (vla-addlightweightpolyline space ptList)) 


; Closes the polyline 
(vla-put-closed lwPlineObj :vlax-true) 


; Restores the previous active layer 
(vla-put-activelayer docObj curLayer) 
(princ) 


) 
4. Save the file and then reload it into AutoCAD. 


5. At the Command prompt, type drawrectangle_activex and press Enter to test the 
function. 


6. Atthe Specify first corner: prompt, specify a point in the drawing area. 


7. Atthe Specify opposite corner: prompt, specify a point in the drawing area that is 
the opposite corner of the rectangle. 


A new layer named Obj is added to the drawing and a new lightweight polyline is drawn 
based on the points specified. 


The completed exercise can be found in the ch12_activex_complete. lsp file, which you can 
download from this book’s web page. 


Monitoring Events with Reactors 

Reactors allow you to monitor for events that occur in a drawing or an application and are one 
of the main advantages of using ActiveX with AutoLISP. Some of the events that you can moni- 
tor for include starting or ending of a command, attaching an Xref, or inserting a block. Using 

reactors, you can ensure certain objects are placed on a specific set of layers without needing to 
switch layers before creating an object. 

In this exercise, you will create two custom functions that AutoCAD will call when a com- 
mand is started, canceled, ends, or fails. You will be monitoring the hatch, bhatch, and 
gradient commands. When any one of those commands is started, AutoCAD sets the Hatch 
layer as current and restores the previous layer if the command ends, fails, or is canceled. 


1. Open the Activex. lsp file in Notepad (Windows) or TextEdit (Mac OS). 


2. Click after the last closing parenthesis of the drawrectangle_activex function and press 
Enter twice. 


USING THE AUTOCAD COM LIBRARY| 343 


3. In the text editor area, type the following: 


; Register the Custom command reactors 
(if (= *rctCmds* nil) 
(setq *rctCmds* 
(vlr-command-reactor nil 
'((:vlr-commandCancelled . apc-cmdAbort) 

(:vlr-commandEnded . apc-cmdAbort) 
(:vlr-commandFailed . apc-cmdAbort) 
(:vlr-commandwillStart . apc-cmdStart) 


) 
(princ) 


) 


; Custom function executed when a command is 
; cancelled, ends, or fails 
(defun apc-cmdAbort (argl arg2) 
; Restore the previous layer 
(if (/= *gClayer* nil) 
(setvar "clayer" *gClayer™*) 


) 


; Clear the global variable 
(setq *gClayer* nil) 
(princ) 


) 


; Custom function executed when a command is started 
(defun apc-cmdStart (argl arg2 / docObj layerObj) 


; Store the current layer 
(setq *gClayer* (getvar "clayer")) 


; Get a reference to the current drawing 
(setq docObj (vla-get-activedocument (vlax-get-acad-object) ) ) 


; Check to see which command has been started 
(cond 
; HATCH, BHATCH or GRADIENT command was started 
((or (= (car arg2) "HATCH") 
(= (car arg2) "BHATCH") 
(= (car arg2) "GRADIENT") 
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enoyu - 


; Create and/or set the Hatch layer current 
(CreateLayer-Activex "Hatch" acRed docObj) 
) 
) 
(princ) 


) 

Save the file and then reload it into AutoCAD. 

At the Command prompt, type drawrectangle-activex and press Enter. 
Follow the prompts that are displayed. 

At the Command prompt, type hatch and press Enter. 


At the Pick internal point or [Select objects/Undo/seTtings]: prompt, specify 
a point inside the rectangle that was drawn in steps 4 and 5. 


Press Enter to end the hatch command. 


A new layer named Hatch is added to the drawing and the new hatch object is placed on 
that layer. 


The completed exercise can be found in the ch12_activex_complete. lsp file, which you can 
download from this book’s web page. 


LEARNING ABOUT OTHER ACTIVEX-RELATED FUNCTIONS 


As I mentioned earlier, this chapter provides an introduction to the various concepts required to 
get started with ActiveX in AutoLISP. There is a wide range of additional AutoLISP functions that 
I wasn’t able to cover in this chapter. The names of these functions begin with the prefixes vla-, 
vlax-, and vlr-. You can learn more about the functions in the AutoCAD Help system by browsing 
to http: //help.autodesk.com/view/ACD/2015/ENU/files/homepage_dev.htn, clicking 
the Functions By Name And Feature Reference link, and then using the links in the Visual LISP 


Extensions for AutoLISP (Windows only) section. 


Leveraging the Windows and Microsoft Office COM 
Libraries 


The Microsoft ecosystem is full of hidden gems that can increase your productivity and improve 
everyday workflows. Many programs that are available for free or for purchase let you create 
proposals or manipulate information in a database, but Windows and Microsoft Office allow 
you to leverage what they do best by using the COM libraries that they expose. There aren’t 
many companies that allow you to manipulate or access their programs programmatically like 
Microsoft does, so take advantage of these benefits whenever possible. 

Using the COM libraries for Windows and Microsoft Office, you can accomplish the following: 


+ 


Create desktop shortcuts, expand environment variables, or even launch an external 
application 
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Create and print documents using Microsoft Word 
Create, manipulate, and print spreadsheets using Microsoft Excel 
Create email messages and access contact lists using Microsoft Outlook 


Access and manipulate data in a database using Microsoft Access 


For specific information on each of these COM libraries, refer to the documentation that 
Microsoft publishes with Windows and the Microsoft Office application you are interested in 
working with. Your favorite Internet search engine will also be of help; search on the keywords 
“Windows Shell object documentation” or “Microsoft Office 2013 Release Developers” to get 
started. 


Accessing the Windows Shell Object 

The Windows Shell object is the graphical interface that you or the user interact with when 
accessing an application or the files stored on the workstation. With the Windows Shell object, 
you can take these actions: 


+ 


+ 


+ 


+ 


Create shortcuts on the desktop or in a file folder 
Access the files on your workstation or a removable/network drive 
Launch an application or URL 


Work with environment variables 


You can create a reference to a Windows Shell object using the following code: 


(vlax-create-object "WScript.Shell") 


Don't forget to release an object returned by the vlax-create-object function from mem- 
ory after you are done with it by using vlax-release-object. Here are two custom functions 
that demonstrate some of the functionality exposed by the Windows Shell object: 


pi 


7 


+ 


7 


; Creates a new shortcut 

; Usage: (CreateShortcut "c:\\mylink. Unk" "c:\\temp\\myfile.lsp") 

; Revise "c:\\mylink.tnk" to a location for which you have write access and change 
3; "c:\\temp\\myfile.lsp" to a valid filename on your workstation. 


(defun CreateShortcut (lnkName Target / wshShell shortcut) 


) 


; Create a reference to Window Scripting Shell Object 
(setq wshShell (vlax-create-object "WScript.Shell") ) 


; Expand the string and any variables in the string 

(setq shortcut (vlax-invoke-method wshShell 'CreateShortcut lnkName)) 
(vlax-put-property shortcut 'TargetPath Target) 

(vlax-invoke-method shortcut 'Save) 


; Release the Window Scripting Shell Object 
(vlax-release-object wshShell) 
(princ) 
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; Shows how to use expanding environment strings 
; Usage: (ExpEnvStr "%TEMP%\\MYDATA") 
; Results of sample: "C:\\Users\\Lee\\AppData\\Local\\Temp\\MYDATA" 
(defun ExpEnvStr (strVal / wshShell strValRet) 
; Create a reference to Window Scripting Shell Object 
(setq wshShell (vlax-create-object "WScript.Shell") ) 


; Expand the string and any variables in the string 
(setq strValRet (vlax-invoke-method wshShell 'ExpandEnvironmentStrings strVal)) 


; Release the Window Scripting Shell Object 
(vlax-release-object wshShell) 


strValRet 
) 


USING THE CORRECT MICROSOFT OFFICE RELEASE 


Microsoft Office and AutoCAD are supported on both 32- and 64-bit platforms. However, Microsoft 
Office 32-bit can be installed on Windows 64-bit whereas AutoCAD 32-bit cannot. Many companies 
install only Microsoft Office 32-bit, because there is less support for 64-bit add-ons for Microsoft 
Office applications than for 32-bit add-ons. Although this typically isn’t an issue, the problem comes 
when you try to use ActiveX to talk to any of the Microsoft Office applications from AutoCAD. 
AutoCAD 64-bit won't allow you to import/access 32-bit database drivers or COM libraries, so 


you need to make sure your workstation is configured correctly by having the proper release of 
Microsoft Office installed. 


The following code helps you locate the Microsoft Office release that a user might have installed on 
their machine, whether they are using Office 32- or 64-bit. The code uses a function named expen- 
vstr, which you saw in the “Leveraging the Windows and Microsoft Office COM Libraries” section. 


; Checks for a specific version of Microsoft Office 
; Microsoft Office 2013 - 15 
; Microsoft Office 2010 - 14 
; Microsoft Office 2007 - 12 
; Microsoft Office 2003 - 11 
; Microsoft Office 2000 - 10 
(defun Get-MSOfficePath (ver / ) 
; Office version 
(setq *MSOfficeVer* (itoa ver)) 


; Office 32-bit path on Windows 64-bit 
(setq *MSOfficePathx86* 
(strcat (ExpEnvStr "%PROGRAMFILES (X86) %") 
"\\Microsoft Office\\Office" (itoa ver) 
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; Office path (Windows 32- or 64-bit) 
(setq *MSOfficePath* 
(strcat (ExpEnvStr "%PROGRAMFILES%" ) 
(cond 
((= ver 15)(streat "\\Microsoft Office " (itoa ver) 
"\\root\\Office" (itoa ver))) 
(strcat "\\Microsoft Office\\Office" (itoa ver)) 


; Return 32-bit location first and then 64-bit 
(cond 
((/= (findfile *MSOfficePath*) nil) 
(strcat *MSOfficePath* "\\") 
) 
((/= (findfile *MSOfficePathx86*) nil) 
(strcat *MSOfficePathx86* "\\") 
) 
a) 


; Example of using the custom function 
(Get-MSOfficePath 15) 
"C:\\Program Files\\Microsoft Office 15\\root\\Office15\\" 


Working with Microsoft Office 


The Microsoft Word object allows you to create an instance of Microsoft Word, which can then 
be used to create or open a document. Once a document has been created or opened, you can 
step through and manipulate the content of the document or print the document to an available 
system printer. 

A reference to a Microsoft Word object can be created using the following code: 


(vlax-create-object "Word.Application") 


If more than one version of Microsoft Office is installed, you can specify which release of 
the product to start by adding a version number to the program ID passed to the vlax-create- 
object function. For the available version numbers, see the “Using the Correct Microsoft Office 
Release” sidebar. 

You can use the following code to create a reference to the Microsoft Excel object: 


(vlax-create-object "Excel.Application") 


You can find the custom functions that show how to work with the Microsoft Word and Excel 
objects in the ch12_mswin_office.1sp file that you can download from this book’s web page. 
The LSP file contains the following custom functions: 
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createmsworddoc The createmsworddoc function creates anew Word document and saves 
it with the name ch12_apc_word_sample.doc to the MyCustomFi les folder. The new Word 
document file is populated with information about some of the nongraphical objects in the 
current drawing. 


printmsworddoc The printmsworddoc function opens the ch12_apc_word_sample.doc 
file that was created with the createmsworddoc function and placed in the MyCustomFi les 
folder. The Word document file is then printed using the default system printer. 


extractattributestoexcel The extractattributestoexcel function creates a new 
spreadsheet file named ch12_attributes.xls in the MyCustomFi les folder. The handle, 
tag, and text string for each attribute in the block references of the current drawing are 
extracted to columns and rows in the spreadsheet. Open the ch12_building_plan. dwg file 
in AutoCAD before executing the function. 


updateattributesfromexcel The updateattributesfromexcel function reads the infor- 
mation from the spreadsheet file named ch12_attributes.xls in the MyCustomF7 les folder. 
The extracted handle in the spreadsheet is used to get the attribute reference and then update 
the tag and text string value that is present in the spreadsheet. Since handles are unique to 
each drawing, you must open the original drawing that the attributes were extracted from. 
Make changes to the third column in the spreadsheet file, such as C2436 to CC2436, before 
opening the ch12_building_plan. dwg file in AutoCAD and executing the function. 


Along with custom functions that work with Microsoft Word and Excel, there are also a few 
functions that demonstrate how to connect to a Microsoft Access database (MDB) file using 
Database Access Object (DAO) and ActiveX Data Object (ADO). The database library you use 
depends on which release of Office you are using. You can find two custom functions that access 
an MDB file in the ch12_mswin_office.1sp file that you can download from this book’s web 
page. 

The LSP file contains the following custom functions: 

accessdatabasedao The accessdatabasedao function makes a connection to the Access 

database ch12_employees.mdb, located in the MyCustomFi les folder. Once a connection to 

the database is made, the records in the Employees table are read and modified. Use this 
function when working with Access 2007 and earlier. 


accessdatabaseado The accessdatabaseado function makes a connection to the Access 
database ch12_employees.mdb, located in the MyCustomFi les folder. Once a connection to 
the database is made, the records in the Employees table are read and modified. Use this 
function when working with Access 2007 and later. 


Chapter 13 


Implementing Dialog Boxes 
(Windows only) 


The goal of any program should be to make end users be productive and feel empowered 
without getting in their way. Your decisions about the number of options and how they are pre- 
sented can make or break a custom function. Include too many, and the user becomes frustrated 
while responding to prompts about options that aren’t used frequently; too few, and the useful- 
ness of the custom function suffers. Dialog boxes allow users to see values that might normally 
be hidden behind a set of prompts and provide input for only those options they are interested 
in changing. A dialog box can also be used to combine multiple functions into a single, easy-to- 
use interface. 

For example, consider the difference between the insert command, which displays 
the Insert dialog box, and the - insert command, which displays a series of options at the 
Command prompt. The insert command allows you to explode a block upon insert and use 
geographical data without affecting the prompt sequence or functionality of the -insert 
command. In this chapter, you will learn to implement dialog boxes for use with AutoLISP® 
programs. 


What Is Dialog Control Language? 


Dialog Control Language (DCL) is the technology used to lay out and design dialog boxes that 
can be used with AutoLISP programs. Support for DCL was originally added to Autodesk® 
AutoCAD® R11 and has remained essentially unchanged through AutoCAD 2015. Dialog boxes 
are defined and stored in ASCII text files with a .dcl extension. Once a DCL file has been cre- 
ated, AutoLISP can then load and display the dialog contained in the DCL file. After the dia- 
log is displayed, AutoLISP is used to control what happens when the user clicks or otherwise 
manipulates the controls in the dialog box. 

A DCL file can contain multiple dialog-box definitions. Each dialog box and control is defined 
through the use of a tile. The appearance of a tile is affected by what are known as attributes— 
think of attributes as the properties of a drawing object. 

With the exception of the tile that defines the dialog box (the dialog tile), tiles typically start 
with a colon followed by the name of the tile type you want to place on the dialog box. The 
dialog tile must start with a user-defined name that is unique in the DCL file; this name is used 
to display the dialog box in the AutoCAD drawing environment. A pair of curly brackets that 
contain the attributes of the tile typically follows the name or type of a tile. Each attribute must 
end with a semicolon. 
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In addition to attributes, some tiles contain nested tiles, which are placed within a tile’s curly 
brackets. Some tile names aren’t followed by a pair of curly brackets because they don’t support 
attributes; these tiles are known as subassemblies. Subassemblies help you implement standard- 
ized tile groupings. The OK and Cancel button tiles used in most dialogs created with DCL are 
examples of subassemblies. 

Listing 13.1 shows an example of a dialog box definition that could be used as part of an alter- 
native to the message box that is automatically displayed with the alert function. Remember, 
the alert function displays a message box with an OK button only. 


LISTING 13.1: Alternative message box 


/* Example message box 
Created on: 5/11/14 */ 
ex_alert : dialog { 
label = "Title"; 
key = "dlg_main"; 


: text { // Custom message 
key = "msg"; 
label = "Custom message here."; 


} 


ok_cancel; // Subassembly 


Figure 13.1 shows what the alternative message box looks like when loaded into the 
AutoCAD drawing environment. A DCL file can also contain comments, which are prefixed 
with // or located between the character groupings /* and */. Both comment styles are shown 
in Listing 13.1. 


FIGURE 13.1: Title 
Alternative message box =e 5 

ustom message here. 
defined with DCL a 


OK Cancel 


MODERNIZED DCL ALTERNATIVES 


DCL has remained unchanged since AutoCAD R12, which is great from a compatibility perspective 
but not from a technology point of view. The controls that you can use on a dialog box defined with 
DCL will seem limited when you consider the countless controls that are available in Windows and 
Windows-based programs. Although the DCL that comes with AutoCAD is limited, there are a few 
alternatives that you can use to enrich the dialog boxes you create. 


Here are the two DCL alternatives that I am aware of: 
ObjectDCL—A technology that must be licensed from DuctiSoft (http: //objectdcl.com) 


OpenDCL—An open source application based on the ObjectDCL application; OpenDCL can be 
downloaded from http: //opendcl.com. 


DEFINING AND LAYING OUT A DIALOG BOX 


ObjectDCL and OpenDCL allow you to implement modern Windows and third-party controls in an 
AutoLISP custom dialog box. You can use tree view, data grid, and HTML viewer controls, among 
many others. Both software solutions also provide WYSIWYG (what you see is what you get) design 
capabilities through their dialog-box editors. 


AutoCAD Managed .NET and the ObjectARX APIs provide alternatives for creating custom AutoLISP 
functions that display custom dialog boxes created with Microsoft’s Windows Presentation 
Foundation (WPF) and Microsoft Foundation Class (MFC). Developing your own dialog boxes 
using WPF and MFC can take additional time (compared to ObjectDCL or OpenDCL), but you own 
all the source code and don’t need to worry about external dependencies. 


Defining and Laying Out a Dialog Box 


DCL files can be created and edited using Notepad, the Visual LISP® Editor, or whichever edi- 
tor you are using for LSP files. Although you can use Notepad, the Visual LISP Editor offers a 


few advantages over Notepad for working with DCL files. It supports color syntax as it does 


with LSP files, but it also has a built-in DCL preview feature. Without the Visual LISP Editor’s 


DCL preview feature, you must write an AutoLISP program that will at least load a DCL file 


and display a dialog box in the AutoCAD drawing environment to see the final appearance of a 


dialog box. 


©) Real World Scenario 


SIMPLIFYING USER INTERACTION AND OPTION PRESENTATION 


Have you ever sat and scratched your head in hopes of deciphering the options displayed as part of 
a prompt string for a command or custom function? Maybe you have tried to use a command that 
presented nested option prompts, and no matter how well you guessed, you got the wrong results. 
Both of these situations waste time. Fortunately, there is a solution to these problems and it is in 
the form of dialog boxes. Dialog boxes, or more specifically DCL in AutoLISP, can be used to improve 
users’ experience by allowing them to follow a nonlinear workflow and provide only the information 
required to complete a task. Users can quickly scan and change values before completing a task. At the 
end of the day, a dialog box can help to reduce clicks, which means saving time—and time is money. 


Defining a Dialog 


Each dialog box you define must contain a dialog tile. The attributes of a dialog tile are used to 
define the dialog’s label (more commonly referred to as the title or caption), add a programmatic 


name known as a key, and set the tile that should have initial focus. The following shows the 
basic syntax of the dialog tile: 
dialog_name : dialog { 


[attributes] 
[tiles] 
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Here are its arguments: 


dialog_name The dialog_name argument represents the name used to reference a dialog 
box within a DCL file. A DCL file can contain more than one dialog tile, but each must have 
a unique name. The same name can be used in different DCL files without any problems. 


attributes The attributes argument is a list of optional attributes that describe the 
dialog tile. An attribute consists of a name and value, separated by an equals sign, and ends 
with a semicolon. For example, label = "Title"; specifies the use of the attribute named 
label and that it should be assigned the value of Title. See Table 13.1 for a list of the attri- 
butes that the dialog tile supports. 


tiles The tiles argument is a list of optional tiles that define the controls that you want 
to display in the dialog box. For information on the tiles that are available, see the “Adding 
Tiles” and “Grouping, Aligning, and Laying Out Tiles” sections later in this chapter. 


Table 13.1 lists and describes the attributes that can be applied to the dialog tile. 


TABLE 13.1: Common attributes used with the dialog tile 


ATTRIBUTE DESCRIPTION 
label The title that is assigned to the dialog box. 
value Alternative to the title attribute. This attribute can be set only with the 


set_tile function. I discuss the set_ti le function later in this chapter, in 
the “Setting the Default Value of an Interactive Tile” section. 


initial_focus The key assigned to the tile in the dialog tile that should have focus by 
default when the dialog box is displayed. 


An example of a dialog tile was shown earlier in this chapter; see Listing 13.1 and Figure 13.1. 


Adding Tiles 

A dialog box can contain a variety of tiles—commonly referred to as controls—that can be used 
to get input from the user. The tiles that are available for placement in a dialog box are common 
to many Windows dialog boxes. The following shows the basic syntax of a tile: 


: tile_name { 
[attributes] 
} 


Here are its arguments: 


tile_name The tile_name argument represents the name of the tile type to place in the 
dialog box. See Table 13.2 for the tile names that are supported. 


attributes The attributes argumentis a list of optional attributes that describe the tile. 
An attribute consists of a name and value, separated by an equals sign, and ends with a semi- 
colon. For example, label = "Controll"; specifies the use of the attribute named label 
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and that it should be assigned the value of Control1. See Table 13.3 for a list of the common 
attributes that tiles support. 


Table 13.2 lists and describes the interactive tiles that can be added to a dialog tile for getting 
input from the user when a dialog box is displayed. 


TABLE 13.2: Interactive tiles available with the dialog tile 


TILE NAME DESCRIPTION 

button Push or command button that, when clicked, executes a function. 

edit_box Free-form text box in which the user can enter an alphanumeric value. 

image Container that displays a slide image. The slide image can be a stand-alone SLB file or 


one from a compiled slide library SLD file. 
image_button Graphical button that displays a slide image that, when clicked, executes a function. 


List_box List box that contains a set of predefined items from which the user can select one or 
more items. 


popup_list Drop-down list that contains a set of predefined items from which the user can choose 
a single item. 


radio_button Option button that allows for a single choice among multiple option buttons. 
slider Scroll bar-like control that allows the user to specify a value within a specific range. 
text Label that displays information to the user or identifies the intention of a control. 
toggle Check-box button that allows for multiple choices. 


Table 13.3 lists and describes some of the most commonly used attributes to control the 
behavior of tiles other than a dialog tile. 


TABLE 13.3: Common attributes used with control tiles 


ATTRIBUTE SUPPORTED TILE(s) DESCRIPTION 
action Allinteractive tiles Function to be executed when the tile is 
clicked. 
allow_accept edit_box, image_button, and Activates the button that is specified 
list_box with the is_default attribute. 
edit_limit edit_box Maximum number of characters that 


can be entered into the text box. 
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TABLE 13.3: Common attributes used with control tiles (CONTINUED) 


ATTRIBUTE SUPPORTED TILE(s) DESCRIPTION 


is_cancel button Indicates that the function associated 
with the button tile’s action attribute 
should be executed when Esc is pressed. 


is_default button Indicates that the function associated 
with the button tile’s action attribute 
should be executed when Enter is 


pressed. 

is_enabled Allinteractive control tiles Indicates that the tile is enabled or 
disabled. 

key Allinteractive control tiles Unique name used to programmatically 


reference the tile. 


label button, edit_box, List_box, Label that describes the intention of the 
popup_list, radio_button, text, tile and is displayed adjacent to the tile. 
and toggle 

list List_box and popup_list Items that are displayed and selectable 


by the user in the list. The character 
sequence \n is used to separate each item 


in the list. 
multiple_select List_box Indicates that the list supports multiple 
selections. 
value text_box and interactive tiles Current value of a tile. 
except button and image_button 
tiles 


To see what values an attribute supports, search on the keywords “programmable dialog box 
reference” in the AutoCAD Help system. Search on the keywords “synopsis predefined attri- 
butes” in the AutoCAD Help system to see the other attributes that are available. 


NOTE All the tiles listed in Table 13.2 are interactive tiles, with the exceptions of the image 
and text tiles. 


Listing 13.2 shows an example of a dialog box that contains a popup_list, two radio_ 
button tiles, and a button tile. Figure 13.2 shows what the dialog box would look like if 
displayed in the AutoCAD drawing environment using AutoLISP. 
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LISTING 13.2: Create Label Object dialog box 


/* Create label object */ 
ex_createLabelObject : dialog { 
label = "Create Label Object"; 
key = "dlg_layer"; 
: popup_list { // Drop-down list 
key = "List_layers"; 
label = "Layer to place object on"; 


: radio_button { // Circle 
key = "opt_circle"; 
label = "Circle"; 


: radio_button { // Octagon 
key = "opt_octagon"; 
label = "Octagon"; 

} 

: button { // Create object button 
key = "btn_create_object"; 


action = "create_object"; 
label = "Create"; 
is_default = "true"; 


} 
cancel_button; // Cancel only button 


FIGURE 13.2 


Create Label Object 
Example dialog box titled 


: Layer to place object on 
Create Label Object seal x 
O Circle 
O Octagon 
Create 


Cancel 


In addition to the tiles listed in Table 13.2, DCL makes use of tile subassemblies. Tile subas- 
semblies are used to provide common arrangements of exit buttons. Table 13.4 shows several 
of the available tile subassemblies that can be used in a dialog tile. You can view the names of 
the subassemblies in the base. dcl file located in the AutoCAD Support folder. A subassembly 
ends with a semicolon, as shown in Listings 13.1 and 13.2. You can’t change the attribute values 
of a subassembly provided by AutoCAD, but you can re-create a subassembly with different 
attribute values in your own DCL files. Use the syntax found in the base .dc1l file as the basis 
for your new subassembly code. The base .dcl file can be found in the AutoCAD support-file 
search path by entering (findfile "base.dcl") at the Command prompt. 


355 


356 |CHAPTER13 IMPLEMENTING DIALOG BOXES (WINDOWS ONLY) 


TABLE 13.4: Tile subassemblies 


TILE SUBASSEMBLY DESCRIPTION 
cancel_button Cancel only button 
ok_button OK only button 

ok_cancel OKand Cancel buttons 
ok_cancel_help_ OK, Cancel, and Help buttons 


Grouping, Aligning, and Laying Out Tiles 

Tiles are stacked vertically in a dialog box by default, unless you use what are called cluster tiles. 
Cluster tiles are used to group and align tiles in rows and columns. Tiles also support several 
attributes that help you control their size and alignment in a dialog box. In addition to cluster 
tiles and attributes, spacer tiles can be used to control the size and alignment of tiles. A spacer 
tile allows for the insertion of empty space between tiles in a dialog box. 


GROUPING TILES INTO CLUSTERS 


Grouping tiles into a cluster allows you to better control how they are aligned or organized in 
the dialog box, in addition to controlling which radio_button tiles are related to each other. A 
cluster tile must be used to restrict the choice of multiple radio_button tiles in a dialog box so 
only one option button can be selected at a time. Tiles can be grouped into columns and rows 
with or without a visual grouping box. Table 13.5 lists and describes the cluster tiles that can be 
used to group tiles. 


TABLE 13.5: Cluster tiles 


TILE NAME DESCRIPTION 
boxed_column Groups tiles into a column and draws a box with a label around the tiles. 
boxed_radio_column Groups related radio_button tiles into a column and draws a box witha 


label around the tiles; tiles are treated as exclusive to each other. 


boxed_radio_row Groups related radio_button tiles into a row and draws a box with a label 
around the tiles; tiles are treated as exclusive to each other. 


boxed_row Groups tiles into a row and draws a box witha label around the tiles. 
column Groups tiles into a column; no grouping box is drawn around the tiles. 
radio_column Groups related radio_button tiles into a column; tiles are treated as exclu- 


sive to each other. No grouping box is drawn around the tiles. 
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TABLE 13.5: Cluster tiles (CONTINUED) 
TILE NAME DESCRIPTION 


radio_row Groups related radio_button tiles into a row; tiles are treated as exclusive 
to each other. No grouping box is drawn around the tiles. 


row Groups tiles into a row; no grouping box is drawn around the tiles. 


Listing 13.3 shows a revised version of the DCL syntax shown in Listing 13.2. The revised 
syntax uses the boxed_radio_column and row cluster tiles to group tiles. Figure 13.3 shows 
what the dialog box would look like if displayed in the AutoCAD drawing environment using 
AutoLISP. 


LISTING 13.3: Create Label Object dialog box with cluster tiles 


/* Create label object */ 
ex_createLabelObject : dialog { 
label = "Create Label Object"; 
key = "dlg_layer"; 
: popup_list { // Drop-down list 
key = "list_layers"; 
label = "Layer to place object on"; 
} 
: boxed_radio_row { 
label = "Shape"; 
: radio_button { // Circle 
key = "opt_circle"; 
label = "Circle"; 
} 
: radio_button { // Octagon 
key = "opt_octagon"; 
label = "Octagon"; 


row { 
: button { // Create object button 
key = "btn_create_object"; 
action = "create_object"; 
label = "Create"; 
is_default = "true"; 
} 


cancel_button; 
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FIGURE 13.3 Create Label Object 
Grouping z 

related tiles Layer to place object on y 
in the Create prere 

Label Object O Circle © Octagon 

dialog box Create Cancel 


ALIGNING AND SIZING TILES 


When a dialog box is displayed, tiles have a default alignment and size assigned to them. In 
most cases, a tile’s size is based on the label text that it is assigned, or the width of the dialog box 
or cluster tile that it is placed within. Table 13.6 describes the tile attributes that can be used to 
control the alignment and size of the tiles in a dialog tile. 


TABLE 13.6: Attributes used with aligning and sizing tiles 


ATTRIBUTE SUPPORTED TILE(s) DESCRIPTION 


alignment All tiles Horizontal or vertical 
alignment of a tile 


children_alignment column, row, boxed_row, boxed_coLumn, Overrides the horizontal or 
boxed_radio_coLumn, boxed_radio_ vertical alignment for all 
row, radio_coLumn, and radio_row tiles contained in a cluster 
tile 


children_fixed_height column, row, boxed_row, boxed_coLumn, Overrides the fixed height 


boxed_radio_coLumn, boxed_radio_ for all tiles containedina 
row, radio_coLumn, and radio_row cluster tile 
children_fixed_width column, row, boxed_row, boxed_coLumn, Overrides the fixed width 
boxed_radio_coLumn, boxed_radio_ for all tiles containedina 
row, radio_coLumn, and radio_row cluster tile 
edit_width edit_box and popup_list Width of the input field, not 
the tile 
fixed_height All tiles Absolute height of a tile 
fixed_width All tiles Absolute width of a tile 
height All tiles Minimum height of a tile; 
might increase when the 
dialog box is displayed 
width All tiles Minimum width of a tile; 


might increase when the 
dialog box is displayed 


DEFINING AND LAYING OUT A DIALOG BOX| 359 


To see which values an attribute supports, search on the keywords “programmable dialog 
box reference” in the AutoCAD Help system. 

In addition or as an alternative to using tile attributes, spacer tiles can be used to increase 
the space between tiles. Table 13.7 lists and describes the spacer tiles that can be used to align 
tiles and control tile size. 


TABLE 13.7: Spacer tiles 


TILE NAME DESCRIPTION 


spacer Inserts a gap of the specified size in the horizontal or vertical direction; the direction 
that the gap is created in is defined by how the tile is clustered with other tiles. 


spacer_0 Inserts a gap that restricts the distribution or automatic resizing of tiles to the left or 
above the spacer tile. 


spacer_1l Inserts a gap of one unit wide by one unit high. 


Listing 13.4 shows a revised version of the DCL syntax shown in Listing 13.3. The revised 
syntax uses the edit_width attribute to size the popup_list tile, the fixed_width and 
alignment attributes on the row tile, the width attribute for the button tile, and a spacer tile to 
control the alignment and sizing of the tiles in the dialog box. Figure 13.4 shows what the dialog 
box would look like if displayed in the AutoCAD drawing environment using AutoLISP. 


LISTING 13.4: Aligning and sizing tiles in the Create Label Object dialog box 


/* Create label object */ 
ex_createLabelObject : dialog { 
label = "Create Label Object"; 
key = "dlg_layer"; 
: popup_list { // Drop-down list 
edit_width = 10; 
key = "List_layers"; 
label = "Layer to place object on"; 
J 
: boxed_radio_row { 
label = "Shape"; 
: radio_button { // Circle 
key = "opt_circle"; 
label = "Circle"; 
} 
: radio_button { // Octagon 
key = "opt_octagon"; 
label = "Octagon"; 
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: row { 
fixed_width = true; 
alignment = right; 
: button { // Create object button 
key = "btn_create_object"; 


action = "create_object"; 
label = "Create"; 
is_default = "true"; 
width = 12; 


} 
: spacer { width = 1; } 
cancel_button; 


FIGURE 13.4 Create Label Object 
Setting the 
i Layer to place object on v 
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Creating and Previewing a Dialog in a DCL File 

You can create a DCL file with Notepad or the Visual LISP Editor; you follow the same pro- 

cess you use to create a LSP file. The only difference is that you specify a file extension of .dcl 
instead of . Lsp. Once you create a DCL file, you can add a dialog box definition to the file. To 
see what the dialog box looks like, you must load the DCL file in the AutoCAD drawing envi- 
ronment and display it. There are two approaches available for viewing a DCL file. The first is to 
create an AutoLISP program that loads and displays the file; the other involves using the Visual 
LISP Editor. (The second approach eliminates the need to write any code.) I discuss how to load 
a DCL file and display a dialog box in the next section. 

The Visual LISP Editor makes it easy to create, modify, and preview a DCL file. When a DCL 
file is open and in the current window of the editor, you can click Tools > Interface Tools > 
Preview in DCL Editor to preview the dialog box. A dialog box allows you to specify which 
dialog in the DCL file to preview. The Visual LISP Editor sends some AutoLISP code to the 
AutoCAD Command prompt and displays the dialog box. Click Cancel or another tile to close 
the dialog box and return to the Visual LISP Editor. 


NOTE The DCL Preview feature requires you to have full read/write access to the AutoCAD 
installation folder. If you don’t have those permissions, you will need to request them from your 
company’s IT department or adjust the permissions yourself using the User Account settings 
through the Windows Control Panel. 


DEFINING AND LAYING OUT A DIALOG BOX 


In this exercise, you will create a DCL file based on the dialog box defined in Listing 13.4 and 
then preview it using the Visual LISP Editor: 


1. 


E E 


In AutoCAD, click the Manage tab > Applications panel > Visual LISP Editor. 
In the Visual LISP Editor, click File > New File. 
Click File > Save As. 


In the Save-as dialog box, browse to the MyCustomFi les folder within the Documents (or 
My Documents) folder, or the location you are using to store DCL files. 


In the File Name text box, type ex_createLabelObject. 
Click the Save As Type drop-down list and choose DCL Source Files. 
Click Save. 


In the text editor window, type the following: 


/* Create label object */ 
ex_createLabelObject : dialog { 
label = "Create Label Object"; 
key = "dlg_layer"; 
: popup_list { // Drop-down list 
edit_width = 10; 
key = "List_layers"; 
label = "Layer to place object on"; 
} 
: boxed_radio_row { 
label = "Shape"; 
radio_button { // Circle 
key = "opt_circle"; 
label = "Circle"; 


radio_button { // Octagon 
key = "opt_octagon"; 
label = "Octagon"; 


} 
row { 
fixed_width = true; 
alignment = right; 
: button { // Create object button 
key = "btn_create_object"; 


action = "create_object"; 
label = "Create"; 
is_default = "true"; 
width = 12; 
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: spacer { width = 1; } 
cancel_button; 


} 


9. Click File > Save. 
10. Click Tools > Interface Tools > Preview DCL In Editor. 


11. In the Enter The Dialog Name dialog box, click OK. That dialog box lists all the dialog- 
box definitions in the DCL file that is open in the editor. 


12. Review the dialog box and click any control to return to the Visual LISP Editor. 


The dialog box you create should look like the one shown earlier, in Figure 13.4. 


Loading and Displaying a Dialog Box 

The Visual LISP Editor makes it easy to preview a dialog box, but it doesn’t allow you to inter- 
act with the tiles on the dialog box. A DCL file must be loaded and displayed with AutoLISP 

to enable user interaction. When a dialog box is being loaded, you can set the initial values of 
each tile and specify the enabled state of each tile. If your dialog box contains any list_box, 
popup_list, image, or image_button tiles, you might have to perform some initialization tasks 
for these tiles. (I cover those tasks in the “Initializing Tiles” section later in this chapter.) 


Loading and Unloading a DCL File 


A DCL file must be loaded into the AutoCAD drawing environment before you can display one 
of the dialog-box definitions in the file. The load_dialog function loads a DCL file and returns 
a random integer value that represents a DCL file ID. A positive DCL file ID value indicates 
that the DCL file was located in the AutoCAD support-file search paths specified in the Options 
dialog box and was successfully loaded; a negative value notifies you that the DCL file wasn’t 
located and loaded. 

The following shows the syntax of the load_dialog function: 


(load_dialog dcl_filename) 


The dcl_filename argument that the load_dialog function expects is a string that repre- 
sents the path to and the filename of the DCL file you want to load. I recommend placing DCL 
files in the AutoCAD support-file search paths. When you do so, only the filename needs to be 
specified, making it easier to move the files on your network if needed. 

Here is an example that loads a DCL file named ex_createLabelObject.dcl with the 
load_dialog function and the return of the DCL file ID, in this instance a value of 101. You 
should always store the DCL file ID in a variable so that you can display and unload a dialog 
box defined in the DCL file. The DCL file was created as part of the exercise in the “Creating and 
Previewing a Dialog in a DCL File” section earlier in this chapter. 


(setq id (load_dialog "ex_createLabelObject.dcl") ) 
101 


LOADING AND DISPLAYING A DIALOG BOX 


The unload_dialog function unloads a dialog box definition from memory; the particular 
dialog is identified by the DCL file ID that was returned by the load_dialog function. The DCL 
file ID changes each time the DCL file is loaded, and the value returned should be stored ina 
variable until the dialog box is no longer needed in the current drawing session. A dialog box 
can be loaded more than once; each time a dialog box is loaded, a new instance of the dialog box 
is stored in memory until it is unloaded. The following shows the syntax of the unload_dialog 
function: 


(unload_dialog dcl_file_id) 


The dcl_file_id argument that the unload_dialog function expects is the same value that 
was returned by the load_dialog function. The unload_dialog function always returns a 
value of nil, and that value has no significant meaning; successfully or unsuccessfully unload- 
ing the dialog box results in the same value of nil. Here is an example of the unload_dialog 
function: 

(unload_dialog id) 
nil 


Displaying a Dialog 
After a DCL file has been loaded, an instance of a dialog box contained in the loaded DCL file 
can be created and displayed with the new_dialog function. The new_dialog function is also 
used to specify a default action for all interactive tiles that don’t have an action assigned to 
them, and the onscreen display location. The new_dialog function returns T if the dialog box 
was successfully created, or it returns nil if the dialog box couldn't be created. 

The following shows the syntax of the new_dialog function: 


(new_dialog dialog_name dcl_file_id [action [point]]) 
Here are its arguments: 


dialog_name The dialog_name argument is a case-sensitive string that specifies the unique 
name of the dialog to create an instance of from the DCL file specified by the dcl_file_id 
argument. The value must exactly match the name applied to the dialog tile and is case 
sensitive. 


dcl_file_id The dcl_file_id argument that the new_dialog function expects is the value 
that was returned by the load_dialog function. 


action The action argument is an optional string that represents an AutoLISP expression. 
This expression is applied to the action attribute of all interactive tiles that aren't assigned 
an action as part of the DCL file; the function is executed when the tile is clicked. Provide "" 
when you want to specify the point argument but no default action. 


point The point argument is an optional 2D point list that represents the onscreen location 
of the dialog box’s upper-left corner. The dialog box is centered by default and can be speci- 
fied with a value of ‘(-1 -1). The upper-left corner of the screen is 0,0. 


Once an instance of a dialog box has been created with the new_dialog function, the start_ 
dialog function must eventually be called. The start_dialog function informs AutoCAD 
that the dialog box is ready for user interaction. Before start_dialog is executed, you should 
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make sure that all initial default values and enabled states have been specified. The next section 
explains how to set the default values for and specify the enabled state of tiles, as well as initial- 
ize lists and images. 

The start_dialog function doesn’t accept any arguments and returns a status value based 
on how the user exited the dialog box. A status value of 1 generally means the user clicked OK 
or a similar button, whereas a value of 0 indicates the user clicked Cancel or the Close button. 
The status value returned by a tile is determined by the value passed to the done_dialog func- 
tion. I cover the done_dialog function later in this chapter, in the “Terminating or Closing a 
Dialog Box” section. You don’t need to worry about executing the done_dialog function if you 
use one of the tile subassemblies that contains the OK or Cancel button mentioned earlier, in the 
“Adding Tiles” section. 

The following example code shows how to load and unload a DCL file, and then create 
and display a dialog box. ex_createLabelObject.dcl is the name of the DCL file that will be 
loaded. The dialog box definition name is ex_createLabelObject. Although in this example 
the DCL file and dialog name are the same, they don’t need to be. I recommend having one dia- 
log box per DCL file and using the same name, but that is just a personal preference. 


; Define a function named createlabelobject 
(defun c:createlabelobject (/ dialog_name id) 
(setq dialog_name "ex_createLabelObject") 


; Load the DCL file named ex_createLabelObject.dcl 
(setq id (load_dialog (strcat dialog_name ".dcl"))) 


; Create a new instance of the dialog named ex_createLabelObject 
; in the center of the screen 
(new_dialog dialog_name id "" '(-1 -1)) 


; Perform additional tasks here 

3 1. Set default values for tiles here with the set_tile function 

2. Set up lists and images here 

3 3. Assign actions here for tiles with the action_tile function 
4. Get information about a tile with get_tile as part of the 


: action assigned with action_tile 
; 5. Terminate the dialog box with the done_dialog function as 
: part of the action assigned with action_tile 


; Display the dialog box and get the exit status 
(setq status (start_dialog)) 


; Unload the DCL file from memory 
(unload_dialog id) 


; Display a custom message based on the exit status of the dialog 
(if (= status 1) 
(alert "User clicked Create.") 
(alert "User clicked Cancel.") 
) 
(princ) 


) 
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Initializing Tiles 

You can manipulate the interactive tiles of a dialog tile in a DCL file once you create an instance 
of a dialog box in memory by using the new_dialog function. You use the value of the key attri- 
bute to reference a tile of a dialog box. Once you have a tile’s key, you can set the default value of 
a tile, set the tile’s enabled state, populate items in the list of a List_box or popup_list tile, or 
assign a slide to an image or image_button tile. 


SETTING THE DEFAULT VALUE OF AN INTERACTIVE TILE 


When you use a dialog box, have you ever noticed that it often remembers the previously 
entered values or that values change based on the controls you interact with? You can assign 
a default value to a tile by using the value attribute in a DCL file or change the default value 
before a dialog box is displayed by using the set_tile function. 

I recommend setting the default value of a tile using the set_tile function, considering it is 
good practice to restore previously entered values each time the dialog box is redisplayed. The 
set_tile function can also be used to change the value of a tile when the user interacts with a 
tile while the dialog box is displayed. I discuss how to handle user interaction with tiles in the 
“Interacting with and Responding to a User” section later in this chapter. 

The following shows the syntax of the set_tile function: 


(set_tile key val) 
Here are its arguments: 


key The key argument is a string that specifies the value assigned to the key attribute of the 
tile you want to modify. 


val The val argument is the string value you want to assign to the tile. An alphanumeric 
string can be assigned to an edit_box tile, whereas an integer formatted as a string can be 
assigned to a List_box, popup_list, toggle, radio_button, or slider tile. The first item in 
the list of a List_box or popup_list tile is 0, the second is 1, and so on. 


The following code shows how to set a value of 1, which means true, to a tile with the key of 
opt_circle using the set_tile function. The key opt_circle refers to the Circle radio_ 
button tile of the ex_createLabel0bject dialog definition you created in the “Creating and 
Previewing a Dialog in a DCL File” section. 


(set_tile "opt_circle" "1") 


NOTE fTheset_tile function can’t be executed until after the new_dialog function has been 
executed. Execute the set_tile function before the start_dialog function to ensure that 
the tile is updated before the dialog box is displayed. 


ENABLING AND DISABLING AN INTERACTIVE TILE 


The tiles of a dialog box are all enabled by default, meaning the user can click or enter text in 
any interactive tile of a dialog box. The is_enabled attribute of a tile controls the tile’s default 
enabled state. When is_enabled is set to false, the user is unable to interact with the tile when 
the dialog box is displayed. The enabled state of a tile can be changed using the mode_tile 
function. 
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I recommend setting the enabled state of a tile using the mode_tile function and not the 
is_enabled attribute. The main reason for doing so is because the disabling of a tile is often 
based on the condition of other tiles or choices made by the user in the dialog box. I discuss how 
to handle user interaction with tiles in the “Interacting with and Responding to a User” section. 

The following shows the syntax of the mode_tile function: 


(mode_tile key mode) 
Here are its arguments: 


key The key argument is a string that specifies the value assigned to the key attribute of the 
tile you want to modify. 


mode The mode argument is an integer value that specifies the mode that should be applied 
to the tile. Table 13.8 lists the available modes that can be applied to a tile. 


TABLE 13.8: Modes available for use with the mode_ti le function 


MODE DESCRIPTION 

(0) Enables an interactive tile 

1 Disables an interactive tile 

2 Sets focus to an interactive tile 

3 Selects the text in an edit_box tile 

4 Toggles highlighting for an image tile 


The following code shows how to disable and then enable a tile with the key of opt_circle 
using the mode_tile function. The key opt_circle refers to the Circle radio_button tile of the 
ex_createLabelObject dialog definition you created in the “Creating and Previewing a Dialog 
ina DCL File” section. 


; Disables tile 
(mode_tile "opt_circle" 1) 


; Enables tile 
(mode_tile "opt_circle" 0) 


NOTE The mode_tile function can’t be executed until after the new_dialog function has 
been executed. Execute the mode_tile function before the start_dialog function to ensure 
that the tile is updated before the dialog box is displayed. 


POPULATING THE ITEMS OF A LIST_BOX OR POPUP_LIST TILE 


The list_box and popup_list tiles allow the user to select one or more predefined values 
from a list. The items available in the list of the two tiles can be specified using the tile’s List 
attribute or AutoLISP functions. The start_list function is used to assign, update, or replace 
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the list of values applied to a List_box or popup_list tile. When a list can be modified, the 
start_list function returns the name of the list; otherwise the function returns nil, indicating 
the list isn’t accessible for modification. Typically, a list isn’t available for modification because 
you provided an incorrect key to the start_list function or the function was called before the 
execution of the new_dialog function. 

The following shows the syntax of the start_list function: 


(start_list key [mode [idx]]) 
Here are its arguments: 


key The key argument is a string that specifies the value assigned to the key attribute of the 
tile you want to modify. 


mode The mode argument is an integer value that specifies how the list currently assigned to 
the tile can be modified. Table 13.9 describes each of the available modes. 


idx The idx argument is an integer value that specifies an item in the list. The item is used 
to indicate which item to change if the mode is set to 1; when the mode is set to 2, it indicates 
the starting item you want to begin appending new items to. 


Table 13.9 describes the modification modes that can be used to edit a list. 


TABLE 13.9: List-editing modes 


MODE DESCRIPTION 
l Next callto add_list replaces the item indicated by the idx argument. 
2 Next call to add_list appends a new item after the item indicated by the idx argument. 


If an index isn’t provided, the new item is appended after the last item in the list. 


3 Items in the list are cleared and a new item is appended. 


After a tile key, mode, and index have been specified with the start_list function, you can 
change or add new items with the add_list function. The add_list function accepts a single 
argument of a string value. This value is the text that will be displayed in the list of the List_ 
box or popup_list tile. If the value is successfully added to the list, the string passed to the 
add_list function is returned; otherwise, nil is returned, indicating the item wasn’t added. 

Once you have modified a list, use the end_list function. The end_list ends the modifica- 
tion of the list that was started with the start_list function. The end_list function returns a 
value of nil regardless of whether the list was successfully modified. 

The following code shows how to replace and assign a list of two values to a popup_list 
tile with the key of List_layers. The list_layers key refers to the Layer To Place Object On 
popup_list tile of the ex_createLabelObject dialog definition you created in the “Creating 
and Previewing a Dialog in a DCL File” section. 


; Clear and replace the list of the popup_list 
(start_list "lList_layers" 2) 
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; Add two items that represent the layers to allow 
(add_list "A-Door") 
(add_list "A-Window") 


; End list modification 
(end_list) 


NOTE Theset_tile and mode_tile functions shouldn't be executed between the use of the 
start_list and end_list functions. Execute the start_list and end_list functions before 
the start_dialog function to ensure that the list is updated before the dialog box is displayed. 


WORKING WITH IMAGE AND IMAGE_BUTTON TILES 


The image and image_button tiles allow you to display a slide in a frame or as a graphical but- 
ton. Based on the image you want to display, you will need to use one of several AutoLISP func- 
tions to initialize the tile. In earlier AutoCAD releases, image_button tiles were used to display 
a preview of a block and then start an AutoLISP expression that would allow the insertion of the 
block. However, the relevance of the image and image_button tiles in a dialog box has dimin- 
ished in recent releases with interfaces such as the ribbon and Tool Palettes window. 

If you want to display a slide (SLD) file in a dialog definition with an image or image_button 
tile, you will want to explore the functions listed in Table 13.10. You can learn more about these 
functions in the AutoCAD Help system. 


TABLE 13.10: AutoLISP functions used to work with image and image_button tiles 


FUNCTION NAME DESCRIPTION 

dimx_tile Returns the width of an image or image_button tile 

dimy_tile Returns the height of an image or image_button tile 

end_image Ends the modification of the current image set by the start_image 
function 

fill_image Draws a filled rectangle in the current image set by the start_image 
function 

slide_image Displays a slide (SLD) file or a slide ina slide library (SLB) file in the cur- 
rent image 

start_image Starts the modification of an image and sets it as the current image 


vector_image Draws a vector in the current image set by the start_image function 
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Interacting with and Responding to a User 


While a dialog box is displayed onscreen, the user is able to interact with the tiles that are 
enabled. As the user interacts with the tiles, the AutoLISP expressions assigned to the tile’s 
action attribute are executed. The AutoLISP expressions can be used to get and set tile and 
attribute values, and to change the enabled state of a tile. 


Specifying the Action of a Tile 


An interactive tile can be assigned an AutoLISP expression that is to be executed when the tile 

is clicked or interacted with. You use the action attribute in a DCL file to assign an AutoLISP 
expression to a tile or the action_tile function. As part of the AutoLISP expression, you can 
get information about the tile that is being interacted with by using several predefined variables. 
Table 13.11 lists the predefined variables that can be referenced by the AutoLISP expression 
assigned to a tile’s action attribute. 


TABLE 13.11: Predefined variables that contain information about the current tile 


VARIABLE NAME DESCRIPTION 


$data Custom information assigned to a tile with the client_data_ti le function. 
$key Key name assigned to the tile. 
$reason Callback reason based on the interaction performed by the user. Possible values are 


1, 2, 3, or 4. 1 indicates the user has clicked or pressed Enter to activate a tile, 2 
means the user exited an edit_box tile, 3 indicates the value of aslider tile has 
changed, and 4 is returned when a list_box or image tile is double-clicked. 


Svalue Current value of the tile. 
$x Coordinate value of an image along its x-axis when an image_button tile is clicked. 
$y Coordinate value of an image along its y-axis when an image_button tile is clicked. 


NOTE After you create an instance of a dialog box with the new_dialog function, you can as- 
sign a string value to a tile from the custom program with the client_data_tile function; 
this is in addition to the tile’s value attribute. When the AutoLISP expressions assigned to the 
tile’s action attribute are executed, you can reference this string value with the $data variable. 
For more information on the client_data_ti le function, refer to the AutoCAD Help system. 


Irecommend setting a tile’s action using the action_tile function to give you the flexibility 
to dynamically change the AutoLISP expression that is assigned while the user is interacting 
with the dialog box. For example, you might want to assign a different action to a button tile 
based on the radio_button tile that the user chooses. 
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NOTE By means of the action attribute or the action_tilLe function, an AutoLISP expres- 
sion can be assigned to all tiles in a dialog box that don’t have a specific expression assigned to 
them. This general action is assigned with the action argument of the new_dialog function 
mentioned earlier, in the “Displaying a Dialog” section. 


The following shows the syntax of the action_tile function: 
(action_tile key expr) 
Here are its arguments: 


key The key argument is a string that specifies the value assigned to the key attribute of the 
tile you want to modify. 


expr The expr argument is a string value that represents the AutoLISP expression that 
should be executed when the user interacts with the tile. 


The following code shows how to assign the AutoLISP expression (alert (strcat "Tile 
key: " S$key)) to the tile with the key of opt_circle using the action_tile function. The key 
opt_circle refers to the Circle radio_button tile of the ex_createLabelObject dialog defini- 
tion you created in the “Creating and Previewing a Dialog in a DCL File” section. 


(action_tile "opt_circle" "(alert (strcat \"Tile key: \" Skey))") 


NOTE Execute the action_tile function before the start_dialog function to ensure that 
the action is assigned to the tile before the dialog box is displayed. 


Getting Information about a Tile 


When a user interacts with the tiles of a dialog box, you will commonly want to get the current 
value of one or all tiles before the dialog box is closed. The current value of the value attribute 
of a tile can be obtained using the get_tile function. If you want to get the value of an attribute 
other than value, you can use the get_attr function. The get_tile and get_attr functions 
return a string value. 


NOTE The get_tile and get_attr functions must be executed before the done_dialog 
function is called to terminate the dialog box. I discuss the done_dialog function in the next 
section. 

The following shows the syntax of the get_tile and get_attr functions: 


(get_tile key) 
(get_attr key attr) 


Here are their arguments: 


key The key argument is a string that specifies the value assigned to the key attribute of the 
tile to query. 


attr The attr argument is a string value that specifies the name of the attribute to query. 


The following code shows how to get the current value of the tile with the key of opt_circle 
using the get_tile function, and get the items assigned to the list attribute of a popup_list 
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tile with the key of List_layers. These tiles are part of the ex_createLabelObject dialog defi- 
nition you created in the “Creating and Previewing a Dialog in a DCL File” section. 


; Gets the current value of the tile 
(get_tile "opt_circle") 
we 


; Gets the current value of the list attribute 
(get_attr "lList_layers" "List") 
"A-Door\nA-Window" 


Terminating or Closing a Dialog Box 

A dialog box must be terminated—or closed—when it is no longer needed and the end user 
wants to return to the drawing area. The done_dialog function is used to indicate that the 
dialog box can be terminated. You commonly add this function as the last part of the AutoLISP 
expression assigned to the action attribute of a button tile such as OK or Cancel that termi- 
nates a dialog box. Before done_dialog is executed, you want to make sure you get the value of 
any tiles or tile attribute values by using the get_tile or get_attr function. 


NOTE The OK and Cancel buttons defined in the predefined subassemblies automatically ex- 
ecute (done_dialog 1) and (done_dialog 0), respectively, when the button is clicked. 
done_dialog needs to be executed only for tiles that close a dialog box. 


The done_dialog function returns a 2D point list that represents the current placement of 
the dialog box onscreen. You can store this value as part of the Windows Registry, and then, to 
restore the location the next time the dialog box is displayed, pass the 2D point list to the 
new_dialog function. 

The following shows the syntax of the done_dialog function: 


(done_dialog [status]) 


The status argument is an integer value that will be returned by the start_dialog func- 
tion. Typically, 0 indicates that the user clicked Cancel or the dialog box was canceled, whereas 
1 indicates that the user clicked OK or an equivalent tile. A value greater than 2 can be passed to 
the status argument. 

The following code shows how to assign a custom action to the OK and Cancel buttons of a 
dialog box. The alert function is called before done_dialog to simply demonstrate that more 
than one AutoLISP function can be called from a tile’s action. 


; Assign an action to the OK button 
(action_tile "accept" "(alert \"OK clicked.\") (done_dialog 1)") 


; Assign an action to the Cancel button 
(action_tile "cancel" "(alert \"Cancel clicked.\") (done_dialog 0)") 


If you have more than one dialog box displayed, in the case of working with nested dialog 
boxes, the term_dialog function can be executed to close all open dialog boxes and return to 
the drawing area. The term_dialog function doesn’t accept any argument values and always 
returns nil. 
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Hiding a Dialog Box Temporarily 
When getting input from the user with a dialog box, it isn’t uncommon to allow the user to 
specify a point or select objects in the drawing area. Before a user can interact with the drawing 
area, the dialog box must be temporarily hidden. The concept of hiding a dialog box involves 
creating a dialog box with new_dialog and then starting user interaction with start_dialog 
in a looping expression that uses the while function. The done_dialog function is then used to 
terminate the dialog box. The status value passed to the done_dialog function is returned by 
the start_dialog function and used to exit or continue looping with the while function. The 
button that should hide the dialog box should use a status value greater than 2 to distinguish 
the status values returned by the OK or Cancel buttons. 

The following DCL syntax defines a sample dialog box named ch13_ex_hidden that will be 
used to demonstrate hiding and showing a dialog box: 


ch13_ex_hidden : dialog 

{ 
label = "Hide/Show Example"; 
key = "dlg_hide"; 

text 


key = "msg"; 
label = "Point: "; 


row { 

fixed_width = true; 

alignment = right; 

: button { 
key = "btn_PickPoint"; 
action = "pickPoint"; 
label = "Pick Point"; 
is_default = "true"; 
width = 12; 

} 

: spacer { width = 1; } 

cancel_button; 


The following AutoLISP code defines a custom function named hiddendlg that loads the 
ex_hidden.dcl file and displays the chl13_ex_hidden dialog box: 


; Display the ch13_ex_hidden.dcl file 
(defun c:hiddendlg (/ dialog_name id status pt) 
(setq dialog_name "ch13_ex_hidden") 


; Load the DCL file named ex_hidden.dcl 
(setq id (load_dialog (strcat dialog_name ".dcl"))) 


(setq status 2) 
(while (>= status 2) 
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; Create the dialog box 
new_dialog dialog_name id "" '(-1 -1)) 


; Added the actions to the Cancel and Pick Point button 
action_tile "cancel" "(done_dialog 0)") 
action_tile "btn_PickPoint" "(done_dialog 2)") 


; Display the point value picked 
if (/= pt nil) 
(set_tile "msg" (strcat "Point: " 
(rtos (car pt)) ", " 
(rtos (cadr pt)) ", " 
(rtos (caddr pt)))) 


3 Check the status returned 
(if (= status (setq status (start_dialog) )) 
(setq pt (getpoint "\nSpecify a point: ")) 
) 
) 


; Unload the dialog box 
(unload_dialog id) 
(princ) 


) 


NOTE The sample DCL syntax and AutoLISP code can be found in the ch13_ex_hidden 
.dcl and ch13_ex_hidden.1tsp files, which you can download from www. sybex.com/go/ 
autocadcustomization. Place the files in the MyCustomF i les folder within the Documents 
(or My Documents) folder, or the location you are using to store the LSP files. Load the LSP file 
and then enter hiddend1g at the Command prompt. Click the Pick Point button and specify a 
point in the drawing area to see the dialog box in action. 


Exercise: Implementing a Dialog Box for the drawplate 
Function 


In this section, you will create a DCL file that defines a dialog box for use with a version of the 
drawp late function that was originally introduced in Chapter 2, “Understanding AutoLISP.” 
The dialog box replaces the width and height prompts and adds an option that controls the cre- 
ation of the label. The key concepts I cover in this exercise are as follows: 


Creating a DCL File A DCL file is used to hold a dialog box definition that can be dis- 
played with the AutoLISP programming language. 


Displaying a Dialog Box A dialog box contained in a DCL file can be loaded and displayed 
in the AutoCAD drawing environment. Once the dialog box has been displayed, the user can 
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interact with the tiles (or controls) on the dialog box. The choices a user makes can then be 


used to control the behavior and output of a custom program. 


The steps in this exercise depend on the completion of the steps in the “Exercise: 
Deploying the drawpLlate Function” section of Chapter 10, “Authoring, Managing, and 
Loading AutoLISP Programs.” If you didn’t complete the steps, do so now or start with the 
ch13_drawplate. lsp and ch13_utility.lsp sample files available for download from www 
.sybex.com/go/autocadcustomi zation. Place these sample files in the MyCustomFiles 
folder under the Documents (or My Documents) folder, or the location you are using to store 
the LSP files. Once the sample files are stored on your system, remove the characters ch13_ 
from the name of each file. 


Creating the drawplate Dialog Box 


Chapter 10 was the last chapter in which any changes were made to the drawplate function. At 
that time, the changes included loading the utility. lsp file and implementing custom help. 
Here you will create a DCL file named drawplate.dcl and then display it in the new version of 


the drawplate function. 
The following steps explain how to create the DCL file for the drawplate function: 


1. In AutoCAD, click the Manage tab > Applications panel > Visual LISP Editor. 
2. Inthe Visual LISP Editor, click File > New File. 

3. Click File > Save As. 
4 


. In the Save-as dialog box, browse to the MyCustomFi les folder within the Documents (or 


My Documents) folder, or the location you are using to store DCL files. 
In the File Name text box, type drawplate. 

Click the Save As Type drop-down list and choose DCL Source Files. 
Click Save. 


oN So 


In the text editor window, type the following: 


/* Draw Plate dialog box 
Used by drawplate.lsp */ 
drawplate : dialog { 
label = "Draw Plate"; 
key = "dlg_drawplate"; 


// Width text box 

: edit_box { 
edit_width = 10; 
key = "txt_width"; 
label = "Width"; 


// Height text box 
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: edit_box { 
edit_width = 10; 
key = "txt_height"; 
label = "Height"; 


} 
// Check box for controlling addition of label 
: toggle { 

key = "chk_label"; 

label = " Add label"; 


// Grouping for button tiles 
row { 
fixed_width = true; 
alignment = right; 


// Create button 


: button { 
key = "btn_create_object"; 
action = "create_object"; 
label = "Create"; 
is_default = "true"; 
width = 12; 


} 
: spacer { width = 1; } 


// Cancel button 
cancel_button; 


} 
9. Click File > Save. 
10. Click Tools > Interface Tools > Preview DCL In Editor. 
11. Inthe Enter The Dialog Name dialog box, choose drawplate and click OK. 


12. Review the dialog box (see Figure 13.5), and click any control to return to the 


Visual LISP Editor. 
FIGURE 13.5 Draw Plate 
New dialog 
box for the walls 
drawplate AEE 
function ase 


Create Cancel 
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Renaming the Existing drawplate Function 


AutoCAD has a few command-naming conventions, and one of those conventions includes pre- 
fixing command names with a hyphen. When an AutoCAD command displays a dialog box, often 
a second command has been created that carries the same name but is prefixed with a hyphen. 
Commands that are prefixed with a hyphen allow you to access most of the functionality of a 
dialog box from the Command prompt through a series of prompt options. Before implementing 
a new version of the drawplate function that displays a dialog box, you must rename the existing 
drawplate function to conform to the established AutoCAD command-naming standards. 

The following steps explain how to rename the drawplate function to -drawplate: 


1. In the Visual LISP Editor, click File > Open File. 


2. Inthe Open File To Edit/View dialog box, click the Files Of Type drop-down list, and 
choose Lisp Source Files. 


3. Browse to and select the drawplate. lsp file and click Open. 
4. In the text editor area, revise the boldface text: 


; Draws a rectangular plate that is 5x2.75 
(defun c:-drawplate ( / ptl pt2 pt3 pt4 width height insPt textValue 
cenPtl cenPt2 cenPt3 cenPt4 old_vars hole_list) 


5. Revise the boldface text: 


; Register the help file for F1l/contextual help support 
(if (findfile "DrawPlate.htm") 

(setfunhelp "c:-drawplate" (findfile "DrawPlate.htm") ) 
) 


6. Click File > Save. 


Defining a New drawplate Function 


Now that you have renamed the existing drawplate function to -drawplate and defined the 
drawplate.dcl file, it is time to implement a new version of the drawplate function. 

The following steps explain how to add the new version of the drawplate function that will 
display the Draw Plate dialog box: 


1. Open the Visual LISP Editor and the drawplate.1sp file if they are not currently open. 
2. In the text editor area, scroll to the bottom of the file and add the following code: 


; Draws a rectangular plate and gets input from a dialog box 

(defun c:drawplate ( / dialog_name id status ptl pt2 pt3 pt4 
width height label insPt textValue cenPtl 
cenPt2 cenPt3 cenPt4 old_vars hole_list) 


; Define the width, height, and label for the plate 

(if (= *drawplate_width* nil) (setq *drawplate_width* 5.0)) 
(if (= *drawplate_height* nil) (setq *drawplate_height* 2.75)) 
(if (= *drawplate_label* nil) (setq *drawplate_label* "1")) 
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; Get recently used values from the global variables 
setq width *drawplate_width*) 

setq height *drawplate_height*) 

setq label *drawplate_label*) 


setq dialog_name "drawplate") 


; Load the DCL file named ex_hidden.dcl 
setq id (load_dialog (strcat dialog_ name ".dcl"))) 


; Create the dialog box 
new_dialog dialog_name id "" '(-1 -1)) 


; Set the default values of the width and height 
set_tile "txt_width" (rtos width) ) 
set_tile "txt_height" (rtos height) ) 


; Set the default for the label 
set_tile "chk_label" label) 


; Add the actions to the Cancel and Create button 
action_tile "cancel" "(done_dialog 0)") 
action_tile "btn_create_object" 
"(setq width (atof (get_tile \"txt_width\"))) 
(setq height (atof (get_tile \"txt_height\"))) 
(setq label (get_tile \"chk_label\")) 
(done_dialog 1)" 


setq status (start_dialog)) 


; Unload the dialog box 
unload_dialog id) 


3 Check the status returned 
if (= status 1) 
(progn 
setq old_err *error* *error* err_drawplate) 


3 Command function being used in custom error handler 
*push-error-using-command* ) 


; Store and change the value of the system variables 


set-sysvars '("osmode" "clayer" "cmdecho") '(0 "o" 0)) 


command "._undo" "_be") 


setq old_vars (get-sysvars '("osmode" "clayer" "cmdecho") )) 
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; Create the layer named Plate or set it current 
(createlayer "Plate" 5) 
(setvar "clayer" "Plate") 


(setq basePt (getpoint "\nSpecify base point for plate: ")) 


3 Set the coordinates to draw the rectangle 
(setq pt1 basePt 

;| lower-left corner ; 
pt2 (list (+ (car basePt) width) (cadr basePt) 0) 
;| lower-right corner |; 
pt3 (list (+ (car basePt) width) (+ (cadr basePt) height) 0) 
;| upper-right corner |; 
pt4 (list (car basePt) (+ (cadr basePt) height) 0) 
;| upper-left corner ; 


; Draw the rectangle 
createrectangle pt1 pt2 pt3 pt4) 


; Create the layer named Holes or set it current 
createlayer "Holes" 1) 
setvar "clayer" "Holes") 


; Calculate the placement of the circle in the lower-left corner 
; Calculate a new point at 45 degrees and distance of 0.7071 from ptl 
(setq cenPtl (polar pt1 (/ PI 4) 0.7071)) 


; Calculate the next point from cenPt along the same angle 

; as the line drawn between pt1 and pt2, and 1 unit less 

; than the distance between pt1 and pt2 

(setq cenPt2 (polar cenPt1 (angle ptl pt2) (- (distance ptl pt2) 1))) 


; Calculate the final two points based on cenPt1l1 and cenPt2 
(setq cenPt3 (polar cenPt2 (angle pt2 pt3) (- height 1)) 
cenPt4 (polar cenPtl (angle ptl pt4) (- height 1))) 


; Append all the calculated center points to a single list 
(setq hole_list (append (list cenPt1) 

(list cenPt2) 

(list cenPt3) 

(list cenPt4) )) 


; Execute the createcircle function for each point 
; list in the in the hole_list variable 
(foreach cenPt hole_list 

(createcircle cenPt 0.1875) 


(if (= "1" label) 
(progn 
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3 Set the insertion point for the text label 
(setq insPt (getpoint "\nSpecify label insertion point: ")) 


; Define the label to add 
(setq textValue 
(strcat "Plate Size: " 
(vl-string-right-trim " .0" (rtos width 2 2)) 
Wy! 
(vl-string-right-trim " .0" (rtos height 2 2)) 


; Create label 

(createlayer "Label" 7) 

(setvar "clayer" "Label") 

(createtext insPt "_c" 0.5 0.0 textValue) 


; Restore the value of the system variables 
set-sysvars '("osmode" "clayer" "cmdecho") old_vars) 


; Save previous values to global variables 
setq *drawplate_width* width) 

setq *drawplate_height* height) 

setq *drawplate_label* label) 


command "._undo" "_e") 


; Restore previous error handler 
setq *error* old_err) 


; End using *push-error-using-command* 
*pop-error-mode* ) 


; Exit "quietly" 
(princ) 


) 
3. Click File > Save. 


Testing the drawplate.lsp Changes 


The following steps explain how to test the -drawplate function in the drawplate. lsp file: 
1. Create a new drawing. 


2. Start the appload command. Load the LSP files drawplate.lsp and utility. sp. If the 
File Loading - Security Concern message box is displayed, click Load. 
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3. At the Command prompt, type -drawplate and press Enter. 


. Atthe Specify base point for the plate or [Width/Height]: prompt, type wand 


press Enter. 


5. Atthe Specify the width of the plate <5.0000>: prompt, type 3 and press Enter. 


. Atthe Specify base point for the plate or [Width/Height]: prompt, type h and 


press Enter. 


7. Atthe Specify the height of the plate <2.7500>: prompt, type 4 and press Enter. 


. Atthe Specify base point for the plate or [Width/Height]: prompt, pick a point 


in the drawing area to draw the plate and holes based on the width and height values 
specified. 


. Atthe Specify label insertion point: prompt, pick a point in the drawing area 


below the plate to place the text label. 


AutoCAD draws the completed plate, as expected. 


The following steps explain how to test the revised version of the drawplate function: 


1. 


Som A oN 


At the Command prompt, type drawplate and press Enter. 


The Draw Plate dialog box is displayed and uses the width and height values specified by 
the -drawplate function. 


In the Draw Plate dialog box, in the Width text box, enter 5. 
In the Height text box, enter 5. 

Clear the Add Label check box. 

Click Create. 


At the Specify base point for the plate or [Width/Height]: prompt, pick a point 
in the drawing area to draw the plate and holes based on the width and height values 
specified. 


AutoCAD draws the completed plate without the label, as expected. 


7. At the Command prompt, type drawplate and press Enter. 


8. In the Draw Plate dialog box, select Add Label. 


9. Click Create, and specify the insertion point for the plate and label. 


AutoCAD draws the completed plate with a label this time. 
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Add Watch dialog box, 321-322 
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ADOs (ActiveX Data Objects), 348 
alert function, 116, 116, 255, 273-274 
aliases, 9 
aligning tiles, 358-360, 360 
alignment attribute, 358 
allow_accept attribute, 353 
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bitwise, 45-46 

comparisons, 126 
angbase system variable, 104-105 
angdir system variable, 103-105 
angle brackets (<>) in prompts, 107 
angle function, 85 
angles and angular values 


conversion functions, 34-35, 57-59, 104, 106 


measuring, 85 

retrieving, 101-106 
angtof function, 59, 104 
angtos function, 57, 104 
Animate tool, 314 
animated progress messages, 135-137, 137 
apc-cmdAbort function, 343 
apc-cmdStart function, 343-344 
apostrophes (’) for lists, 73 
appautoload system variable, 296, 304 
append access mode, 233 
append function 

list elements, 79-80 

XData, 182 
APPID symbol table, 181, 200, 206 
Application Compilation Options page, 317 
Application Directory page, 317 


application names, defining and registering, 181 


application object, 338-339 

Application Options page, 317 

Application Preferences dialog box 
environment variables, 26, 289 


search paths, 271, 281, 283, 287-288, 290-291 
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support and trusted files, 290, 300-301 


system variables, 25 
Application property, 337 
appload command, 12, 68, 281-282, 284 
apply function, 261 
Apropos window, 307, 307 
Apropos Results window, 307, 307 
Area property, 165 
arguments 

command, 31 

errors in, 252-253 

functions, 34-35 

number of, 253 
arrays 

defining, 333-335 

lists. See lists 
ASCII files 

access modes, 233 

DCL, 349 

support for, 231 

text editors, 274 
ascii function, 59 
assoc function 

dictionaries, 213, 215 

lists, 91, 146-147, 168 
asterisks (*) 

DCL comments, 350 

multiplication, 41-42 
atan function, 43 
atof function, 59 
atoi function, 59 
atoms, 16-17, 71 
attaching XData to objects, 181-183 
attext.dvb file, 238 
attributes 

blocks 

extraction program, 192-196 
references, 176-179 

dialog boxes, 349 

tiles, 351-354 
aunits system variable, 103-104 
AutoCAD 

calculator, 89-90 

commands, 30-33 

loading LSP files into, 68-70, 69-70 


AutoCAD Object Library Reference and 


Developer’s Guide, 338 


AutoLISP Developer’s Guide, 19 
AutoLISP Reference, 19 
autoload function, 283-284, 299 
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background color for editor window, 308 
backslashes (\) 
directory paths, 232 
prompt messages, 106, 114 
strings, 56 
trusted locations, 290 
badcode function 
creating, 254-259 
formatting, checking, and debugging, 
318-320, 319 
stepping through and inspecting, 320-323, 
321-323 
balancing parentheses, 1, 5, 252, 312-313 
base.dcl file, 355 
base points, 100, 100 
bills of materials 
creating, 187-198, 189, 197-198 
writing to external files, 248-250, 250 
bitwise operations, 44—47 
blackboard, 25 
block attribute extraction program, 192-196 
-block command, 203 
block definitions, 176 
creating and modifying, 208-210 
room labels, 217-218, 218 
symbol tables, 200, 206 
Block objects, 339 
block references 
creating and modifying, 176-179, 177 
room labels, 219-221 
block symbol table, 200, 206 
Blocks collection, 339 
boole function, 46 
boundp function, 127 
boxed_column cluster tile, 356 
boxed_radio_column cluster tile, 356 
boxed_radio_row cluster tile, 356 
boxed_row cluster tile, 356 
branches. See conditions and branches 
Break On Error tool, 314 
breakpoints, 313-314, 321, 321 


Breakpoints window, 323 
Browse For Folder dialog box 
directories, 240 
support and trusted files, 288, 290, 300 
browsing 
for files, 238-240, 239 
objects, 315, 315 
Build Options tab, 315 
Build Output window, 311, 312, 316, 319-320 
bundles, plug-in, 284, 293-296 
button tile, 353 
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C: prefix, 34-36 
cal command, 89 
calculating geometric values, 84—90 
calculators, AutoCAD, 89-90 
callout balloons, 167, 167 
cancel_button tile subassembly, 356 
car function, 75-77, 147, 168 
case of strings, 55-56 
case sensitivity, 18, 27 
Catch-All-Apply-Error data type, 260-261 
CCircs function, 264-266 
cdr function, 75-77, 147, 168 
celtype system variable, 207 
Centerlines layer, 204-205 
CFG (configuration) files, 21, 231 
change command, 7 
change history, 277 
changeattvalue function, 220-221 
characters 
reading from files, 234-235 
writing to files, 235-236 
checking 
badcode function, 318-320, 319 
code, 311, 312 
children_alignment attribute, 358 
children_fixed_height attribute, 358 
children_fixed_width attribute, 358 
chr function, 58 
circle command, 2, 3, 264 
circles 
attaching XData to, 182-183 
properties, 167, 170-171 
classes, 329, 337 
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clayer system variable, 207 
client_data_tile function, 369 
close function, 236 
closing 
dialog boxes, 371 
files, 236 
clusters of tiles, 356-357, 358 
cmdactive system variable, 31 
collections, 328-329 
colons (:) 
prompts, 107 
tiles, 349 
color command, 32 
ColorIndex property, 331 
coloring syntax, 308, 308-309 
ColorMethod property, 331 
column cluster tile, 356 
COM (Component Object Model). See ActiveX 
and COM libraries 
command function, 30-31 
graphical objects, 143, 147, 161 
PAUSE variable, 97 
point lists, 72 
symbol tables, 203 
command-line history, 117-118 
command macros, 19 
Command prompt 
custom user-input functions, 111-113 
distance and angular values, 101-106 
guidelines, 106-107 
initializing input and keywords, 108-111 
numeric values, 99-100 
overview, 98-99, 99 
point list values, 100-101, 100-101 
room labels, 222-224 
string values, 107-108 
command-s function, 32-33, 266 
commands 
AutoCAD and third-party, 30-33 
displaying dialog boxes, 33 
overview, 3-5 
undefining and redefining, 279-280 
versions, 32 
comments 
code, 271, 276-279, 310 
DCL files, 350 
common errors, 252-253, 253-254 


384 


COMPARISONS +» DEFAULT VALUES 


comparisons 
grouping, 126 
selection filters, 160-161 
values, 120-125 
compiling 
LSP and PRJ files into VLX files, 317-318 
projects, 323-324 
complex objects, 173 
block references, 176-179, 177 
polylines, 173-176 
Component Object Model (COM). See ActiveX 
and COM libraries 
concatenating strings, 48—49, 48 
cond function, 120, 129-131 
conditions and branches, 120 
comparisons 
grouping, 126 
values, 120-125 
if conditions, 127-129 
multiple conditions, 129-131 
overview, 5-7, 7 
repeat function, 133-137, 137 
validating values, 126-127 
configuration (CFG) files, 21, 231 
cons function, 74, 145-146 
Console window, 305, 306, 310-311, 311 
control characters 
prompt messages, 106, 114 
strings, 56 
controls. See tiles 
converting 
degrees to radians, 34-35, 106 
lists and strings, 90 
measurement units, 88-89 
numeric values to other number types, 60-61 
numeric values to strings, 57-58 
strings and values, 56, 58-60 
strings to sentence case, 56 
vla-object values to enames, 339 
coordinate systems, translating, 88 
copying 
code, 256 
files, 243 
cos function, 43 
Create BOM File dialog box, 238-239, 239 
Create CSV File dialog box, 250 
Create Label Object dialog box 
aligning and sizing tiles, 359-360, 360 
cluster tiles, 357, 358 


creating, 355, 355 
createcircle function, 93 
CreateLayer-ActiveX function, 340-341 
createlayer function, 65, 217, 275-276 
createmsworddoc function, 348 
createrectangle function, 65, 275 
CUI/CUIx files, 271 
curly brackets ({}) for tiles, 349-350 
current drawing object, 338-339 
cursors in user-input functions, 112 
custom applications, restricting, 291 
custom dictionaries, 210 

creating, 213-215 

managing, 215-216 

storing information in, 215 
custom error handlers 

defining and using, 262-263 

exercise, 266-269 
custom functions 

defining, 33-34 

returning values from, 61-63 

using, 35-36 
cvunit function, 88-89 


D 


DAOs (Database Access Objects), 348 
data types 
converting, 57-61 
overview, 28-30 
$data variable for tile actions, 369 
Database Access Objects (DAOs), 348 
DCL (Dialog Control Language), 116, 349-351 
creating and previewing dialog boxes in, 
360-362 
loading and unloading files, 362-363 
.dcl extension, 349 
DCL Preview feature, 360 
debugging, 251 
badcode function, 318-320, 319 
code, 313-314 
execution problems, 253, 254 
load problems, 252, 253 
decimal points (.) 
command names, 30 
dotted pairs, 28 
real numbers, 28 
decrementing values, 41 
default values 
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prompts, 107 
tiles, 365 
DefaultFormatForSave environment variable, 27 
defining 
application names, 181 
arrays, 333-335 
custom error handlers, 262-263 
custom functions, 33-34 
dialog boxes, 351-352 
drawplate function, 376-379 
plug-in bundles, 294-296 
user-defined variables, 21-23 
user-input functions, 111-113 
definitions, blocks, 176 
creating and modifying, 208-210 
room labels, 217-218, 218 
symbol tables, 200, 206 
defun function, 8, 34, 262 
degrees, converting to radians, 34-35, 106 
Delete method for collections, 328 
deleting. See removing 
deploying 
DrawPlate.bundle, 303-304 
drawplate function, 301-302, 302 
programs, 291-294 
Developer Help Home Page, 19 
dialog boxes, 349 
commands displaying, 33 
creating and previewing, 360-362 
DCL for, 349-351, 362-363 
defining, 351-352 
displaying, 363-364 
drawplate function, 373-380, 375 
hiding, 372-373 
terminating, 371 
tiles 
actions, 369-370 
adding, 352-356, 355 
aligning and sizing, 358-360, 360 
grouping into clusters, 356-357, 358 
information about, 370-371 
initializing, 365-368 
Dialog Control Language (DCL), 116, 
349-351 
creating and previewing dialog boxes in, 
360-362 
loading and unloading files, 362-363 
dialog tiles, 351-352 
dictadd function, 213-214 


dictionaries, 210 


accessing and stepping through, 210-213 


creating, 213-215 

extension, 180, 210 

managing, 215-216 

room labels, 217 

storing information in, 215 
dictnext function, 211-212 
dictremove function, 215-216 
dictrename function, 215-216 
dictsearch function, 213, 215 
dimscale system variable, 8 
dimstyle symbol table, 200, 206 
dimx_tile function, 368 
dimy_tile function, 368 
directories 

creating, 243 

listing files in, 240-242 

managing, 243 
disabling 

program loading, 291 

tiles, 365-366 
displaying 

dialog boxes, 33, 363-364 

messages, 254-259 

temporary vectors, 118-120, 119 
distance function, 85 
distance values 

measuring, 85 

retrieving, 101-106 
distof function, 59, 103 
distributing programs, 292 
division 

operation, 41-42 

by zero, 42, 61-63 
documentation 

accessing, 19 

programs, 292 
done_dialog function, 364, 370-372 
dotted pairs, 71 

creating, 145-146 

description, 28-29 

element access, 146-147 

values, 144 
Drafting Settings dialog box, 26 


drag and drop in loading programs, 281 


drawcircle function, 276 


drawing rectangles. See drawplate function 


exercise 
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DrawPlate.bundle file 
creating, 302-303 
defining, 294-296 
deploying and testing, 303-304 
drawplate function exercise 
creating, 36-38 
defining, 376-379 
deployment, 298-304, 302 
dialog boxes, 373-380, 375 
errors, 266-269 
help support, 299-300 
holes for, 90—96, 96 
objects, 187-198, 189, 197-198 
projects, 323-324 
user input, 137-141, 141 
values, 63-70, 69-70 
drawplate.lsp file 
adding functions to, 66-67 
creating, 64 
testing changes, 379-380 
drawrectangle function, 275-276 
DrawRectangle_ActiveX function, 341 
dsettings command, 26 
dtr function, 34-35 
dumpallproperties function 
object properties, 162-165 
symbol tables, 205 
DXF group codes, 28, 144-145 
helper functions, 170 
values, 148-149 
XData-related, 180-182 


E 


edit_box tile, 353 
edit_limit attribute, 353 
edit_width attribute, 358 
editing 
programs, 274 
Windows Registry entries, 230 
editing environments, 272 
elements in lists. See lists 
else expression, 127 
empty lists, 28 
enabling tiles, 365-366 
enames (entity names) 
conversions, 339 
description, 29 


passing, 161 
working with, 143-144 
end_image function, 368 
end_list function, 367 
entdel function 
objects, 171-172, 208 
symbol tables, 207 
Enter The Dialog Name dialog box, 362, 375 
entget function 
dictionaries, 210 
handles, 145 
object properties, 168-169 
symbol tables, 204-205 
tables, 148 
XData, 182, 184-185 
entity data lists, 71 
description, 143-144 
element access, 146-147 
object properties, 168-170 
entity names (enames) 
conversions, 339 
description, 29 
passing, 161 
working with, 143-144 
entlast function, 152 
entmake function 
block definition objects, 209 
block references, 176-177 
blocks, 208 
graphical objects, 147-151 
polylines, 173-176 
symbol tables, 203-204 
undo actions, 264, 264 
entmakex function 
blocks, 208 
dictionaries, 213 
graphical objects, 150-151 
symbol tables, 203 
entmod function 
object properties, 168-169 
symbol tables, 205 
tables, 148 
XData, 182 
entnext function, 152-153 
entsel function, 153-154 
entupd function 
object properties, 168-169 
XData, 182 


environment variables 
accessing, 26-27 
description, 20 
file locations, 242-243 
eq function, 122-123 
equal function, 122-123 
equal signs (=) 
equality tests, 121-122 
selection filters, 161 
value comparisons, 120, 125 
equality tests, 121-123 
*error* function, 262-263 
error messages, 319 
Error Trace window, 314, 322-323, 323 
errors, 251 
catching, 260-261 
common, 252-253, 253-254 
displaying messages, 254-259 
drawplate function, 266-269 
error handlers, 251, 262-263 
grouping functions, 263-266, 264, 266, 
268-269 
identifying and tracking down, 251-253, 
253-254 
tracing functions, 259-260 
Esc key, 262-263 
events monitoring, 342-344 
Excel objects, 347-348 
exclamation points (!) 
expressions, 1, 16-17 
with variables, 22 
executing 
code, 310-311, 311 
expressions, 18-19 
execution problems, 253, 254 
existence of list elements, 82-83 
exp function, 43 
expandvariable function, 53 
expenvstr function, 346-347 
Expert mode in New Application wizard, 317 
explode command, 279-280 
exponential notation, 28 
expressions 
commands and input, 3-5 
conditional and repeating, 5-7, 7 
executing, 18-19 
grouping, 7-9, 9 
loading, 9-13, 13 
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storing, 9-13, 13, 271-272 
syntax, 16-18, 17 
working with, 1-3, 3 
expt function, 43 
extAttsFurnBOM function, 248 
extended data. See XData (extended data) 
extended records (XRecords), 20, 215 
extension dictionaries, 180, 210 
extensions, files, 244 
external deployment, 292-294 
external files, 227 
accessing data from, 231 
closing, 236 
exercise, 244-250, 250 
layers based on, 245-247 
opening and creating, 231-234 
reading characters and lines from, 234-235 
writing characters and lines to, 235-236, 
248-249 
extnames system variable, 205 
extractattributestoexcel function, 348 


F 


false value, 120 

FAS files, 316-317 

feedback to users, 97—98, 113-114 
command-line history, 117-118 
Command prompt messages, 114-116 
message box and status bar messages, 

116-117, 116-117 
File Loading - Security Concern message box, 
289-290, 289 

files 
browsing for, 238-240, 239 
copying, 243 
environment variables for, 242-243 
expression execution from, 19 
extensions, 244 
listing, 240-242 
loaded automatically, 282-283 
locating, 237-238 
managing, 243 
modification date and time, 244 
names, 232-234, 243 
paths, 232-233, 244 
program. See programs 
reading and writing data, 244-250, 250 
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removing, 243 
size, 244 
fill_image function, 368 
filter command, 161 
filter lists, 72 
filtering selected objects, 160-161 
findfile function, 237-238 
finding points, 86-87 
findtrustedfile function, 238, 291 
fix function, 60 
fixed_height attribute, 358 
fixed_width attribute, 358 
flags 
block-type, 208 
initget, 108-109 
float function, 60 
focus in graphics window, 120 
foreach function, 78-79, 132 
form-closing comments, 310 
Format Edit Window, 310 
Format Options dialog box, 309-310, 309 
Format Selection tool, 310 
formatting 
badcode function, 318-320, 319 
code, 307, 309-310, 309 
forward slashes (/) 
DCL comments, 350 
directory paths, 232 
division, 41-42 
equality tests, 121-122 
prompts, 107 
Function Listing option, 19 
functions 
COM libraries, 329, 344 
defining, 33-34 
errors in, 253 
grouping, 263-266, 264, 266, 268-269 
listing, 307, 307 
in lists, 73 
returning values from, 61-63 
startup, 280-281 
tracing, 259-260 
unique names, 24 
user-input, 111-113 
using, 35-36 
furnbom function, 192-196 
furnbomexport function, 248-250 


furntools.Isp file, 190-192, 196-198, 197-198 
fuzzy factor in equality tests, 122 


G 


gcd function, 42 
geomcal.arx file, 89 
geomcal.crx file, 89 
geometric values, calculating, 84-90 
get_attr function, 370-371 
Get-DXF-Value function, 189-190 
Get-Sysvars function, 91-93 
get_tile function, 370-371 
getangle function, 103-106 
GetBoundingBox method, 332 
getcfg function, 231 
getcorner function, 101 
GetDictionaryByKeyEntry function, 211 
getdist function, 102 
getenv function, 27, 242-243 
getfiled function, 238-240 
getint function, 99 
getkword function, 110-111 
getorient function, 104-106 
getpoint function, 4, 100-101 
getpropertyvalue function 
objects, 162, 165-166 
polylines, 176 
symbol tables, 205, 207 
getreal function, 4, 99-100 
getstring function, 107-108, 110 
getvar function, 25-26 
global variables, 23-25 
unique names, 24 
watches, 314 
GlobalVar function, 24-25 
graphical objects, 143 
adding to drawings, 147-151, 150-151 
COM libraries, 339-342 
entity names and dotted pairs, 143-147 
selecting. See selecting objects 
graphics windows, 118-120, 119 
grclear function, 120 
grdraw function, 118-119 
greater than (>) operators, 8 
comparing values, 121, 123-125 
selection filters, 161 
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greatest common denominator function, 42 
grouping 
comparisons, 126 
expressions, 7-9, 9 
functions, 263-266, 264, 266, 268-269 
tiles into clusters, 356—357, 358 
grread function, 111-113 
grtext function, 117, 117, 135 
grvecs function, 119, 119 
guidelines for prompts, 106-107 


H 


handent function, 145, 339 
handles of objects, 145, 339 
hard-coded paths, 232-233 
height attribute for tiles, 358 
help and Help system, 19 
COM classes, 337 
drawplate function, 299-300 
for programs, 293, 296-298 
help function, 296-297 
Help reference page, 337 
hiding dialog boxes, 372-373 
highlighting objects, 172 
history 
of changes, 277 
command-line, 117-118 
HKEY_CURRENT_USER key, 228 
HKEY_LOCAL_ MACHINE key, 228 
hyphens (-) 
in commands, 33, 376 
subtraction, 40—41 


I 


I selection method, 156 

IDE (integrated development environment), 305 
identifying errors, 251-253, 253-254 
if function, 6, 120, 127-129 

image tiles, 353, 368 

image_button tiles, 353, 368 

implied selection, 156 

importing COM libraries, 336-337 
incrementing values, 41 

indexes for list elements, 75, 77 

INI (initialization) files, 231 
initcommandversion function, 32 


initdia function, 33 
initget function, 108-111 
initial_focus in dialog tiles, 352 
initialization (INI) files, 231 
initializing 
tiles, 365-368 
user input and keywords, 108-111 
inline comments, 278 
inline variable expansion, 52 
input 
command prompt. See Command 
prompt 
drawplate function, 137-141, 141 
initializing, 108-111 
Insert dialog box, 209 
insert objects, 176 
inserting block references, 176, 219-221 
insertion points in user prompts, 222-224 
Inspect window, 314 
inspecting badcode function, 320-323, 321-323 
installers, 294 
integers, 28 
bitwise operations, 44—47 
dividing, 41 
greatest common denominator, 42 
integrated development environment (IDE), 305 
interacting with users, 97-98 
command prompt. See Command prompt 
feedback, 113-118, 116-117 
graphics windows, 118-120, 119 
interactive object selection, 153-154 
inters function, 87 
INTersection Object Snap mode, 87 
invoking methods, 331-332 
is_cancel attribute, 354 
is_default attribute, 354 
is_enabled attribute, 354, 365 
ispropertyreadonly function 
objects, 162, 166-167 
symbol tables, 205 
IsString function, 29-30 
itoa function, 58 


K 


key attribute for tiles, 354 
$key variable for tile actions, 369 
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keys 
dialog tiles, 351 
dotted pairs, 145-146 
Windows Registry, 228-229 
keywords, initializing, 108-111 


L 


label attribute for tiles, 354 
labels 
dialog tiles, 352 
room. See room labels 
Last Error Source option, 314 
last function, 77-78 
Layer collection, 339 
-layer command, 4, 203 
layer symbol table, 200, 206 
layers 
adding, 247-248 
creating, 275-276 
in external files, 245-247 
moving objects to, 190-192 
layoutlist function, 213 
length 
lists, 79 
strings, 49-50 
length function, 79 
less than (<) operators 
comparing values, 121, 123-125 
selection filters, 161 
libraries. See, ActiveX and COM libraries 
lightweight polylines, 173, 175-176 
linear programs, 120 
lines (code) 
reading from files, 234-235 
writing to files, 235-236 
lines (objects) properties, 167, 170-171 
-linetype command, 203 
LISP Files To Include page, 317 
list attribute for tiles, 354 
list_box tiles, 353, 366-368 
list-editing modes, 367 
list function, 73-74 
ListBlockAtts function, 178-179 
listing 
files, 240-242 
functions and variables, 307, 307 
object properties, 162-165 


ListOSPolyline function, 174-175 
lists, 28, 71 
calculating geometric values, 84-90 
converting with strings, 90 
creating, 73-74 
drawplate function exercise, 90—96, 96 
elements, 74-75 
appending, 79-80 
existence, 82-83 
removing, 81-82 
retrieving, 75-78 
sorting, 84 
stepping through, 78-79 
substituting, 81 
entity data lists, 71, 143-144 
accessing, 146-147 
object properties, 168-170 
overview, 71-72 
load function, 281 
load_dialog function, 362-363 
Load/Unload Applications dialog box, 12, 13, 
281-282 
loading LSP files into AutoCAD, 68, 69 
working with, 284-287, 285 
loading 
code, 313 
DCL files, 362-363 
debugging, 252, 253 
LSP files into AutoCAD, 68-70, 69-70 
programs, 12-13, 13, 274, 274, 281 
automatically, 282-284 
Load/Unload Applications dialog box, 
284-287, 285 
manually, 281-282 
utility.lsp file, 298-299 
LoadLayers function, 245-248 
local deployment, 292-294 
local variables, 8 
vs. global, 23-25 
watches, 314 
LocalVar function, 25 
locating 
files, 237-238 
programs, 287-291 
log function, 43 
logand function, 45-46 
logior function, 44-45 


looping expressions, 5-7, 7, 131-132 


set number of times, 132-133 
while condition is met, 133-137, 137 


lsh function, 46 
LSP files, 271-272 


compiling into VLX files, 317-318 
creating, 11-12 
loading into AutoCAD, 68-70, 69-70 


ltype symbol table, 200, 206 
lunits system variable, 102 
lwpolyline entity, 176 


M 


machine screw plan view, 151, 151 
macros, 19 

make files, 317-318 

Managed .NET APT, 351 

manual program operations 


deploying, 293 
loading, 282-283 


matching parentheses, 1, 5, 252, 312-313 
math functions 


addition and subtraction, 40-41 
advanced, 43 

basic, 39-40, 42-43 

bitwise operations, 44—47 
multiplication and division, 41-42 


matrices 


defining, 334 
transformation, 119 


max function, 42 


MDB (Microsoft Access database) files, 348 


measurements 


angular and distance values, 85 
unit conversions, 88-89 


member function, 82-83 

memory management for XData, 184 
menu (MNL) files, 271 

messages 


Command prompt, 114-116 

displaying, 254-259 

message box and status bar, 116-117, 
116-117 

prompts, 106 


methods in COM libraries, 329-332 


Microsoft Access database (MDB) files, 348 


Microsoft Foundation Class (MFC), 351 


LOOPING EXPRESSIONS 


Microsoft Office 
COM libraries, 344-348 
Excel objects, 347-348 
release issues, 346-347 
Word objects, 347-348 
min function, 42 
minus signs (-) 
in commands, 33, 376 
subtraction, 40-41 
minusp function, 43, 127 


+ NIL VALUE 


missing parentheses, 1, 5, 252, 312-313 


missing quotation marks, 252 
MNL (menu) files, 271 
mode_tile function, 365-366, 368 
modification date and time of files, 2: 
modifying 
block definitions, 208-210 
block references, 176-179, 177 
objects, 161-162 
symbol tables, 202, 205-207 


44 


XData attached to objects, 184-186 


modular code, 275-276 
monitoring events, 342-344 
moving objects to layers, 190-192 
mtext command, 48 

multiple condition tests, 129-131 
multiple_select attribute, 354 
multiplication, 41—42 


N 


namedobjdict function, 210, 214 
names 
dictionary keys, 215-216 
drawplate function, 376 
entity. See enames (entity names) 
files, 243 
functions, 34-35 
programs, 292 
symbol table entries, 205-207 
tiles, 349, 351-352 
unique, 24 
nentsel function, 153-154 
nested tiles, 350 
New Application wizard, 317 
new_dialog function, 363-365 
New Project dialog box, 315, 323-324 
nil value, 120, 125 
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nongraphical objects, 199 OddOrEven function, 259-260 
COM libraries, 339-342 ok_button tile subassembly, 356 
dictionaries, 210-216 ok_cancel tile subassembly, 356 
room labels. See room labels ok_cancel_help_ tile subassembly, 356 
symbol tables, 199-210 old-style polylines, 173-175 
not equal to operator 1+ function, 6, 41 
equality tests, 121-122 Open dialog box, 288, 301 
selection filters, 161 Open File To Edit/View dialog box, 306, 318-319, 
not functions, 46, 121, 125 376 
Notepad for program editing, 272-273 open function, 231-232 
nth function, 76-78 OpenDCL application, 350-351 
Null function, 127 opening external files, 231-234 
numberp function, 127 operating system files, 227 
numeric values browsing for, 238-240, 239 
Command prompt, 99-100 information about, 244 
converting strings to, 58-60 listing, 240-242 
converting to other number types, 60-61 locating, 237-238 
converting to strings, 57-58 managing, 243 
Windows Registry and Plist, 227-231 
o option lists in prompts, 107 
: Options dialog box 
Object Model, 337, 338 DCL files, 362 


object snap bitwise operations, 45-47 environment variables, 27 


Object Snap mode, 86-87 search paths, 271, 281, 283, 287-288, 290 


Object Snap tab, 26 : support and trusted files, 290, 300 
ObjectARX (ARX) API and files, 185, 282, 351 or operations 

ObjectDCL application, 350-351 bitwise, 44-45 

objects, 143 


comparisons, 126 
osmode system variable, 26, 44 
osnap function, 86-87 


adding to drawings, 147-151, 150-151 
block references, 176-179, 177 

COM libraries, 326-327, 339-342 
deleting, 171-172 


dictionaries, 210-216 P 
drawplate stuff, 187-198, 189, 197-198 PackageContents.xml file, 294-296 
entity names and dotted pairs, 143-147 pan command, 118 
extended data. See XData (extended data) parentheses () 
handles, 145, 339 balancing, 1, 5, 252, 312-313 
highlighting, 172 expressions, 16-17, 17 
modifying, 161-162 functions, 35-36 
moving layers, 190-192 lists, 71 
polylines, 173-176 paths, file, 244 
properties description, 232-233 
exercise, 170-171 support files, 237-238, 287-289 
getting and setting, 165-168, 167 PAUSE variable, 23, 31, 97 
listing, 162-165 periods (.) 
updating, 168-170 command names, 30 
room labels. See room labels dotted pairs, 28 
selecting. See selecting objects real numbers, 28 


symbol tables, 199-210 PI variable, 23 


PICKFIRST data type, 154 
PICKSET data type, 154 
PIN input function, 112-113 
pipe symbols (|) for comments, 278 
pline command, 76, 173 
plinetype system variable, 173 
Plist (property list) files, 20 
creating and querying entries, 228-229 
storing information in, 227-228 
plot command, 33 
plug-in bundles, 284, 293-296 
plus signs (+) for addition, 40—41 
point lists, 71-72 
calculating geometric values, 84-90 
Command prompt, 100-101, 100-101 
creating, 74 
points 
calculating, 86 
finding and snapping to, 86-87 
prompting for, 340-342 
translating, 88 
polar function, 86 
polylines, 173-176 
*pop-error-mode* function, 266 
populating tiles, 366-368 
popup_list tiles, 353, 366-368 
predefined variables, 23, 369 
Preferences dialog box 
programs, 11, 64, 273 
search paths, 281, 283 
prefixes for program names, 292 
previewing dialog boxes, 360-362 
prin1 function, 115, 255 
princ function, 8, 115-116, 255 
print function, 115, 255 
printmsworddoc function, 348 
PRJ files, compiling into VLX files, 
317-318 
progn function, 128-129 
program IDs, 326 
programs 
comments, 276-279 
creating, 272-274, 274 
deploying, 291-294 
drawplate function, 298-304, 302 
editing, 274 
editor. See Visual LISP Editor (VLIDE) 
help for, 296-298 
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loading, 12-13, 13, 274, 274, 281 
automatically, 282-284 
Load/Unload Applications dialog box, 

284-287, 285 
manually, 281-282 

location, 287-291 

modular code, 275-276 

restricting, 291 

startup functions, 280-281 

progress messages in status bar area, 135-137, 
137 

Project Files tab, 315 

Project Properties dialog box, 315-316, 316, 324 

projects 

compiling, 323-324 

creating, 315-317, 316 

prompt function, 5, 79, 114-115, 255 
prompts. See Command prompt 
properties 

COM libraries, 329-331 

objects 
exercise, 170-171 
getting and setting, 165-168, 167 
listing, 162-165 
updating, 168-170 

property list (Plist) files, 20 

creating and querying entries, 

228-229 

storing information in, 227-228 
PRV files, 317-318 
-purge command, 207 
*push-error-using-command* function, 266 
*push-error-using-stack* function, 266 


Q 
querying 
Windows Registry entries, 228-229 
XData attached to objects, 184-186 
quickcalc command, 89 
quotation marks (“) 
case sensitivity with, 18 
missing, 252 
prompt messages, 106, 114 
strings, 28, 49, 56 
quote (’) function 
dotted pairs, 145-146 
graphical objects, 150 
lists, 73-74 
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RADIANS + SEARCH PATHS FOR SUPPORT FILES 


R 


radians, converting degrees to, 34-35, 106 
radio_button tiles, 353 
radio_column cluster tiles, 356 
radio_row cluster tiles, 357 
reactors, event monitoring with, 342-344 
read access mode, 233 
read-char function, 234-235 
read-line function, 234-235 
read-only files, 232 
read-only properties, 166-167 
ReadFile function, 235 
reading 
characters and lines from files, 234-235 
files, 244-250, 250 
real values 
description, 28 
dividing, 41 
$reason variable for tile actions, 369 
rectang command, 8, 80 
rectangles 
drawing, 275-276 
exercise. See drawplate function exercise 
RectangularRevCloud function, 8-9 
redefine command, 279-280 
redefining commands, 279-280 
redraw function, 118, 172 
Reference topics, 19 
references 
block, 176-179, 177, 219-221 
objects using handles, 145 
regapp function, 181 
regen command, 118 
registering application names, 181 
Registry, 20, 227-228 
creating and querying entries, 228-229 
editing and removing entries, 230 
relative paths, 238 
rem function, 42 
RemoveDimOverride function, 186 
removing 
block definition objects, 208 
dictionaries, 215-216 
files, 243 
list elements, 81-82 
objects, 171-172 
Registry entries, 230 


selection set objects, 157 
symbol table entries, 207 
XData, 186 
renaming 
dictionary keys, 215-216 
drawplate function, 376 
files, 243 
symbol table entries, 205-207 
reopening files, 307 
repeat function, 6-7, 131-133 
repeating expressions, 5-7, 7, 131-132 
set number of times, 132-133 
while condition is met, 133-137, 137 
replacing strings, 51-53 
restricting custom applications, 291 
return-nested function, 241 
returning values from functions, 61-63 
revcloud command, 8 
Review Selections/Build Applications page, 317 
room labels, 216-217 
adding to drawings, 224-225, 224-225 
block definitions, 217-218, 218 
block references, 219-221 
createlayer function, 217 
user prompts, 222-224 
roomlabel function, 222-224 
roomlabel_createblkdef function, 218 
roomlabel_insertblkref function, 221 
row cluster tile, 357 
RRC function, 9 
rtos function, 5 
description, 57 
distance values, 103 
rubber-band lines, 100, 100 


S 


/s function, 61-63 

s:startup function, 280-281 

safearrays, 29 

Save As dialog boxes, 9 
dialog boxes, 361 
drawplate dialog box, 374 
environment variables, 27 
programs, 273, 306 

scope of variables, 23-25 

scripts, 19 

search paths for support files, 237-238, 287-289 


searching for text patterns in strings, 50-51 


secureload system variable, 291 


Select Layer Data File dialog box, 247 


selecting objects 
based on XData, 186-187 


filtering selected objects, 160-161 


individual, 152-154 
selection sets, 154 
creating, 154-157 
limits, 156 
object management, 
157-158 
stepping through, 158-160 
selection filters, 160-161 
selection names, 154, 161 
semicolons (;) 
attributes, 349, 352 
comments, 277-278, 310 
file browsing, 239 
program locations, 89 
search paths, 289 
subassemblies, 355 
tiles, 349, 352 
sentencecase function, 56 
seqend objects, 176 
Set Color dialog box, 32 
Set-DXF-Value function, 189-190 
Set-Sysvars function, 91-93 
set_tile function, 365, 368 
setcfg function, 231 
setenv function, 27 
setfunhelp function, 296-298 
setpropertyvalue function 
objects, 162, 165-166 
polylines, 176 
symbol tables, 205, 207 
setq function, 6, 21-22 
setRGB method, 332 
setvar function, 25-26, 207 
setview function, 207 
Shell Object, 345-346 
shift operations, 46 
shortcuts, creating, 345-346 
Simple mode for New Application 
wizard, 317 
sin function, 43 
single-line comment style, 277-278 
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size 
files, 244 
tiles, 358-360, 360 
slashes (/) 
DCL comments, 350 
directory paths, 232 
division, 41-42 
equality tests, 121-122 
prompts, 107 
slide_image function, 368 
slider tile, 353 
snapping to points, 86-87 
snvalid function, 205 
sorting list elements, 84 
spacer tiles, 359 
spaces 
expressions, 17 
strings, 108 
special characters in command names, 30 
sqrt function, 43 
square brackets ([]) in prompts, 107 
ssadd function, 157-158 
ssdel function, 157-158 
ssget function 
selection filters, 161 
selection sets, 154-156 
XData, 186-187 
ssgetfirst function, 156-157 
sslength function, 158-159 
ssmemb function, 158, 160 
ssname function, 158-159 
ssnames, 154, 161 
ssnamex function, 157 
sssetfirst function, 157 
start_dialog function, 363-364, 372 
start_image function, 368 
start_list function, 366-368 
Start Screen, 9 
startup functions, 280-281 
Startup Suite, 282, 286-287, 286 
static filenames, 232 
status bar messages, 116-117, 116-117, 135-137, 
137 
Step Into tool, 313-314, 322 
Step Out tool, 313-314 
Step Over tool, 313-314, 322 
stepping through 
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badcode function, 320-323, 321-323 
dictionaries, 210-213 
lists, 78-79 
selection sets, 158-160 
symbol tables, 200-202 
storing 
expressions, 9-13, 271-272 
information in custom dictionaries, 215 
values, 19-21 
strcase function, 55-56 
strcat function, 49 
strings, 28 
case, 55-56 
concatenating, 48-49, 48 
converting numeric values to, 
57-58 
converting to numeric values, 58-60 
converting with lists, 90 
length, 49-50 
overview, 48-49 
replacing, 51-53 
retrieving, 107-108 
searching for text patterns in, 50-51 
trimming, 54-55 
value operations with, 56 
strlen function, 49-50 
style symbol table, 200, 206 
subassemblies, 350, 355-356 
subdirectories in search paths, 238 
subroutines in COM libraries, 329 
subst function, 81, 168, 185 
substituting list elements, 81 
substr function, 51 
substrings, 54-55 
subtraction, 40-41 
support 
configuring, 300-301 
for programs, 293 
support files search paths, 237-238, 287-289 
symbol tables, 199-200 
accessing and stepping through, 200-202 
adding entries, 202-205 
block definitions, 208-210 
modifying entries, 202, 205-207 
removing entries, 207 
working with, 207 
syntax 
coloring, 308, 308-309 
expressions, 16-18, 17 


system variables, 20 
symbol tables, 207 
working with, 25-26 


T 


T variable, 23 
tab character, 308 
tables. See symbol tables 
tblnext function 
description, 200-201 
dictionaries, 211 
tblobjname function 
description, 200-202 
symbol tables, 204, 207 
tblsearch function, 6 
description, 201-202 
symbol tables, 207 
temporary filenames, 233-234 
temporary vectors, 118-120, 119 
term_dialog function, 371 
terminating dialog boxes, 371 
terpri function, 114-115 
test conditions, 120 
TestEscErr function, 263 
testing 
DrawPlate.bundle, 303-304 
drawplate.lsp changes, 379-380 
equality, 121-123 
function deployment, 301-302, 302 
greater or less values, 123-125 
multiple conditions, 129-131 
nil, 125 
programs, 292 
text object properties, 167, 170-171 
text patterns in strings 
replacing, 51-53 
searching for, 50-51 
text tile, 353 
TextEdit program, 272 
textpage function, 117-118, 120 
textscr function, 117-118, 120 
then expression, 127 
third-party commands, 30-33 
3D polylines, 173 
tildes (~) for NOT function, 46 
tiles 
actions, 369-370 
adding, 352-356, 355 


aligning and sizing, 358-360, 360 
default values, 365 
dialog boxes, 349 
enabling and disabling, 365-366 
grouping into clusters, 356-357, 358 
image and image_button, 368 
information about, 370-371 
initializing, 365-368 
list_box and popup_list, 366-368 
subassemblies, 355-356 

Toggle Breakpoint option, 313 

toggle tiles, 353 

toggleint function, 47 

toggling states, 47 

tokens, command, 31 

toolbars for projects, 316 

topic files for help, 297 

Topic Map option, 19 

trace function, 259 

Trace window, 305, 306 

Trace Stack window, 314 

tracing functions, 259-260 

tracking down errors, 251-253, 253-254 

trans function, 88 

transformation matrices, 119 

TransformBy method, 334 

translating points, 88 

trigonometric functions, 43 

trimming strings, 54-55 

troubleshooting 
badcode function, 318-320, 319 
code, 313-314 
execution problems, 253, 254 
load problems, 252, 253 

True value, 23, 120 

Trusted File Search Path - Security Concern 

dialog box, 290 

trusted locations, 289-291, 289 

trusted paths, 300-301 

trustedpaths system variable, 301 

type function, 29 


U 


u command, 171 

ucs symbol table, 200, 206 

undefine command, 279-280 
undefining commands, 279-280 
underscores (_) in command names, 30 
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undo actions, grouping functions into, 263-266, 
264, 266, 268-269 
undo command, 151, 171 
unexpected data, 23 
unique names, 24 
units, converting, 88-89 
unload_dialog function, 363 
unloading DCL files, 362-363 
untrace function, 259 
updateattributesfromexcel function, 348 
updating 
block definition objects, 208 
object properties, 168-170 
programs, 292 
user-defined variables, 20-23 
user input and interaction, 97-98 
command-line history, 117-118 
command prompt. See Command prompt 
drawplate function, 137-141, 141 
feedback, 113-118, 116-117 
functions, 111-113 
graphics windows, 118-120, 119 
initializing, 108-111 
overview, 3-5 
user prompts for room labels, 222-224 
utility.lsp file 
creating, 67-68 
loading, 298-299 
objects, 187-188 
room labels, 217 


vV 


validating 
code, 310-314, 311-312 
values, 126-127 
value attribute for tiles, 354 
$value variable for tile actions, 369 
values, 39 
bitwise operations, 44—47 
comparing, 120-125 
data type conversions, 57-61 
dialog tiles, 352 
equality, 121-123 
geometric, 84-90 
math functions, 39-43 
returning from functions, 
61-63 
storing and retrieving, 19-21 
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strings. See strings 
validating, 126-127 
variables 
environment, 20, 26-27 
inline expansion, 52 
listing, 307, 307 
local, 8 
predefined, 23 
scope, 23-25 
system, 20, 25-26 
user-defined, 20-23 
watches, 314, 321-322, 322 
variants, 29, 332-333 
vector_image function, 368 
vectors, temporary, 118-120, 119 
versions 
commands, 32 
program IDs, 326 
view symbol table, 200 
Visual LISP Editor (VLIDE), 252, 272, 305 
accessing, 305, 306 
browsing objects, 315, 315 
code 
checking, 311, 312, 318-320, 319 
coloring syntax, 308, 308-309 
commenting, 310 
debugging, 313-314, 318-320, 319 
executing, 310-311, 311 
loading, 313 
validating, 310-314, 311-312 


compiling LSP and PRJ files into VLX files, 


317-318 
dialog boxes, 351, 360-361 
file management by, 306-307 
formatting 
badcode function, 318-320, 319 
code, 309-310, 309 
overview, 307 
matching parentheses, 312-313 
projects 
compiling, 323-324 
creating, 315-317, 316 


stepping through and inspecting badcode 


function, 320-323, 321-323 
working with, 318 
vl-bb-ref function, 25 
vl-bb-set function, 25 


vl-catch-all-apply function, 42, 260-261 
vl-catch-all-error-message function, 261 
vl-catch-all-error-p function, 261 
vl-directory-files function, 240-241 
vl-every function, 83 

vl-file-copy function, 234, 243 
vl-file-delete function, 243 
vl-file-directory-p function, 240-241 
vl-file-rename function, 234, 243 
vl-file-size function, 244 
vl-file-systime function, 244 
vl-filename-base function, 244 
vl-filename-directory function, 244 
vl-filename-extension function, 244 
vl-filename-mktemp function, 233-234 
vl-list* function, 74 

vi-list-length function, 79 
vl-list->string function, 90 
vl-load-all function, 282 
vl-load-com function, 336 
vl-member-if function, 83 
vl-member-if-not function, 83 
vl-mkdir function, 243 

vl-position function, 77 
vl-prin1-to-string function, 56 
vl-princ-to-string function, 5, 56 
vl-propagate function, 25 
vl-registry-delete function, 230 
vl-registry-descendents function, 229-230 
vl-registry-read function, 228-229 
vl-registry-write function, 228-231 
vl-remove function, 81-82 
vl-remove-if function, 82 
vl-remove-if-not function, 82 
vl-some function, 83 

vl-sort function, 84 

vl-sort-i function, 84 

vl-string-elt function, 59 
vl-string-left-trim function, 54 
vl-string->list function, 90 
vl-string-mismatch function, 51 
vl-string-position function, 51 
vi-string-right-trim function, 54 
vl-string-search function, 50-51 
vl-string-subst function, 52, 135 
vl-string-translate function, 53 
vl-string-trim function, 54 


vla-add function, 209 
vla-delete function, 207, 336 
vla-get-activedocument function, 339 
vla-get-application function, 337 
vla-get-handle function, 339 
vla-get-red function, 336 
vla-load-com function, 207, 337-338 
vla-object data type, 326, 339 
VLA-Objects, 29 
vlax-3d-point function, 335 
vlax-add-cmd function, 36 
vlax-create-object function, 326, 345, 347 
vlax-dump-object function, 329-330, 338 
vlax-ename->vla-object function, 339 
vlax-for function, 132, 328-329 
vlax-get-acad-object function, 338 
vlax-get-object function, 326-327 
vlax-get-or-create-object function, 327 
vlax-get-property function, 330-331, 336 
vlax-import-type-library function, 336 
vlax-invoke-method function, 331-332, 336 
vlax-machine-product-key function, 230 
vlax-make-safearray function, 333-334 
vlax-make-variant function, 332-333 
vlax-map-collection function, 329 
vlax-method-applicable-p function, 332 
vlax-property-available-p function, 331 
vlax-put-property function, 330-331 
vlax-release-object function, 327, 345 
vlax-remove-cmd function, 36 
vlax-safearray-fill function, 335 
vlax-safearray-get-dim function, 335 
vlax-safearray-get-element function, 
334-335 
vlax-safearray-get-l-bound function, 335 
vlax-safearray-get-u-bound function, 335 
vlax-safearray->list function, 335 
vlax-safearray-put-element function, 334-335 
vlax-safearray-type function, 335 
vlax-tmatrix function, 334 
vlax-user-product-key function, 230 
vlax-variant-change-type function, 333 
vlax-variant-type function, 333 
vlax-variant-value function, 333 
vlax-vla-object->ename function, 339 
VLIDE. See Visual LISP Editor (VLIDE) 
vlide command, 305 
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VLX files 
compiling LSP and PRJ files into, 317-318 
description, 315 

vport symbol table, 200, 206 


Ww 


Watch window, 314, 321-322, 322 
wcmatch function, 51 
while function, 131, 133-137, 137 
width attribute for tiles, 358 
wildcard characters 
selection filters, 161 
string searches, 51 
Window Attributes dialog box, 308, 309 
Windows and Microsoft Office, 344-348 
Windows Presentation Foundation (WPF), 351 
Windows Registry, 20, 227-228 
creating and querying entries, 228-229 
editing and removing entries, 230 
Windows Shell Object, 345-346 
Word objects, 347-348 
WPF (Windows Presentation Foundation), 351 
wrapping functions, 263-266, 264, 266, 
268-269 
write access mode, 233 
write-char function, 235-236 
write-line function, 235-236 
writing 
bill of materials, 248-250, 250 
characters and lines to files, 235-236 
files, 244-250, 250 
modular code, 275-276 


X 


$x variable for tile actions, 369 

XData (extended data), 20-21, 180 
attaching to objects, 181-183 
defining and registering application names, 

181 

memory management for, 184 
object properties, 169 
querying and modifying, 184-186 
removing, 186 
selecting objects based on, 186-187 
working with, 180-181 

xdroom function, 184 
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xdsize function, 184 Z, 


XRecords (extended records), 20, 215 zero, division by, 42, 61-63 


zerop function, 43, 127 
Y zoom command, 118 
$y variable for tile actions, 369 zooming function, 34 
zw function, 34 
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